NUI-Widgets documentation has moved to Storybook hosted on Github Pages.

ButtonDropdown

import ButtonDropdown from '@concur/nui-widgets/lib/Buttons/ButtonDropdown';

DropdownButtons are a specialized form of Button in which the button itself does not invoke any action but instead presents a list of actions in a dropdown menu.

Examples

Because React doesn't output newlines between elements, dropdown buttons on the same line are displayed flush against one another. To preserve the spacing between multiple inline buttons, wrap buttons in <ButtonToolbar> components.

Types

Different dropdown button types (styles) have different contextual meaning in the application. Use the type property to specify the appropriate dropdown button type.

<ButtonToolbar muted>
    <ButtonDropdown
        id='dropdownExample1'
        title='Default'
        type='default'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        id='dropdownExample2'
        title='Primary'
        type='primary'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        id='dropdownExample3'
        title='Create'
        type='create'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        id='dropdownExample8'
        title='Link'
        type='link'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
</ButtonToolbar>

<ButtonToolbar muted>
    <ButtonDropdown
        id='dropdownExample11'
        muted
        title='Default'
        type='default'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        id='dropdownExample12'
        muted
        title='Primary'
        type='primary'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        id='dropdownExample18'
        muted
        title='Link'
        type='link'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
</ButtonToolbar>

Sizes

There are three supported dropdown button sizes: 'lg' (the default), 'md' and 'sm' . Use the size property to set the appropriate size.

<ButtonDropdown
    id='dropdownExample1'
    title='Large'>
    <MenuGroup>
        <MenuItem>First Item</MenuItem>
        <MenuItem>Second Item</MenuItem>
    </MenuGroup>
</ButtonDropdown>

<ButtonDropdown
    id='dropdownExample2'
    size='md'
    title='Medium'>
    <MenuGroup>
        <MenuItem>First Item</MenuItem>
        <MenuItem>Second Item</MenuItem>
    </MenuGroup>
</ButtonDropdown>

<ButtonDropdown
    id='dropdownExample3'
    size='sm'
    title='Small'>
    <MenuGroup>
        <MenuItem>First Item</MenuItem>
        <MenuItem>Second Item</MenuItem>
    </MenuGroup>
</ButtonDropdown>

Disabled State

Set the disabled property to change the dropdown button’s state to disabled.

<ButtonToolbar muted>
    <ButtonDropdown
        disabled
        id='dropdownExample1'
        title='Default'
        type='default'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        disabled
        id='dropdownExample2'
        title='Primary'
        type='primary'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        disabled
        id='dropdownExample3'
        title='Create'
        type='create'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
</ButtonToolbar>

Disabled State (Focusable)

Set the allowFocusOnDisable property to true, along with the disabled property. This allows a button to receive focus when it is disabled by keeping it in the tab cycle. This is good practice for accessibility, as it prevents the button from being hidden from assistive technologies (like screen readers). Further, if allowFocusOnDisable is true, then the disabledMessage and enabledMessage properties MUST also be set to a localized string. These messages should be such that they help users of accessible technologies understand the button’s state changes.

<ButtonToolbar muted>
    <ButtonDropdown
        allowFocusOnDisable
        disabled
        disabledMessage='Please complete required fields to enable dropdown'
        enabledMessage='Select items dropdown enabled'
        id='dropdownExample1'
        title='Default'
        type='default'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        allowFocusOnDisable
        disabled
        disabledMessage='Please complete required fields to enable dropdown'
        enabledMessage='Select items dropdown enabled'
        id='dropdownExample2'
        title='Primary'
        type='primary'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
    <ButtonDropdown
        allowFocusOnDisable
        disabled
        disabledMessage='Please complete required fields to enable dropdown'
        enabledMessage='Select items dropdown enabled'
        id='dropdownExample3'
        title='Create'
        type='create'>
        <MenuGroup>
            <MenuItem>First Item</MenuItem>
            <MenuItem>Second Item</MenuItem>
        </MenuGroup>
    </ButtonDropdown>
</ButtonToolbar>

Labels

In cases when the text of a button may change, use a label to describe the button. Set the textLabel property to add a label for a button.

NOTE: By default, the font weight of the text label matches the font weight of the button text. If you choose to alter the font weight of the text label, it may not line up properly with the button text due to font rendering inconsistencies between browsers.

const menuItems = [
    'First Item',
    'Second Item',
    'Third Item'
];

class HIGButtonDropdownEx04 extends React.Component {
    constructor(props) {
        super(props);

        this.state = {
            filter1: 'First Item',
            filter2: 'Second Item',
            filter3: 'Third Item'
        };
    }

    _handleSelection = (list, eventKey) => {
        this.setState({
            ['filter' + list]: eventKey
        });
    }

    _renderMenuItems = (list) => {
        const currentFilter = this.state['filter' + list];
        return menuItems.map((item, index) => {
            return (
                <MenuItem
                    active={currentFilter === item}
                    eventKey={item}
                    key={index}>{item}</MenuItem>
            );
        });
    }

    render() {
        return (
            <div>
                <ButtonDropdown
                    id='dropdownExample1'
                    onSelect={this._handleSelection.bind(this, 1)}
                    textLabel='Filter:'
                    title={this.state.filter1}
                    type='default'>
                    <MenuGroup>
                        {this._renderMenuItems(1)}
                    </MenuGroup>
                </ButtonDropdown>
                <ButtonDropdown
                    id='dropdownExample2'
                    onSelect={this._handleSelection.bind(this, 2)}
                    textLabel='Filter:'
                    title={this.state.filter2}
                    type='link'>
                    <MenuGroup>
                        {this._renderMenuItems(2)}
                    </MenuGroup>
                </ButtonDropdown>
                <ButtonDropdown
                    id='dropdownExample3'
                    onSelect={this._handleSelection.bind(this, 3)}
                    textLabel={<span><i className='icon-filter' /> <strong>Filter:</strong></span>}
                    title={this.state.filter3}
                    type='link'>
                    <MenuGroup>
                        {this._renderMenuItems(3)}
                    </MenuGroup>
                </ButtonDropdown>
            </div>
        );
    }
}

Dropdown menus are composed of a collection of 1 or more MenuGroup and MenuItem components. MenuGroup components accept a header prop which renders a group title list item.

<ButtonDropdown
    id='dropdownHeaderExample'
    size='lg'
    title='Dropdown'>
    <MenuGroup header='Group 1'>
        <MenuItem>First Item</MenuItem>
        <MenuItem>Second Item</MenuItem>
    </MenuGroup>
    <MenuGroup header='Group 2'>
        <MenuItem>First Item</MenuItem>
        <MenuItem>Second Item</MenuItem>
    </MenuGroup>
</ButtonDropdown>

Usage

ButtonDropdown

Properties

Property Type Default Description
id String Required id attribute of the <button> tag. Required for accessibility.
title Node Required Content (usually text) displayed on the button.
disabledMessage String Required if allowFocusOnDisable is true A visually hidden hint message to be conveyed to users of assistive technologies like screen readers, when button changes state to disabled. This message should explain why this action is disabled or how to enable it. For example, “This action is restricted to some users” OR “Please fill required fields before submitting”
enabledMessage String Required if allowFocusOnDisable is true A visually hidden hint message to be conveyed to users of assistive technologies like screen readers, when button changes state to enabled. This message should call out the fact that this action is now enabled. For example, “Press submit to proceed”
allowFocusOnDisable Boolean false Setting this to true allows the button to receive focus when it is disabled.
buttonClassName String   Custom classes to be added to the <button> tag.
children Node   Collection of MenuItem components to be shown in the dropdown menu.
className String   Custom classes to be added to the containing <div> tag.
disabled Boolean false Controls whether the button is enabled or disabled.
dropdownMaxHeight Number   Overrides the maximum height of the dropdown menu (in pixels).
flipContainer Element or Element[]   Used to create a boundary for the underlying Popper to stay within.
muted Boolean false Renders the button in an alternate “muted” style where the background color is white and the border color is the brand color for the type.
noCaret Boolean false Controls whether the caret (“^”) shows on the button after the title.
open Boolean false Controls whether the dropdown is visible when initially rendered.
placement String or String[] ['bottom-start', 'top-start', 'bottom-end', 'top-end'] Placement of the popover relative to the target element. Options are 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end', 'right', 'right-start', 'right-end'. If you use an array of strings, the first item in the array is the default placement and the following ones are chosen in order as fallback placements if the preceding ones don’t work.
pullRight Boolean false Aligns the right edge of the dropdown with the right edge of the button.
size String 'lg' Button size. Options are 'lg', 'md', 'sm'.
textLabel Node   Label text that describes a button. This text will appear to the left of the button.
textLabelClassName String   Custom classes to be added to the <div> tag around the text label.
type String 'default' Button type. Options are 'default', 'primary', 'create', 'link'.

Callbacks

Property Parameters Description
onClose   Callback function fired when dropdown closes.
onSelect eventKey, event Callback function fired when a menu item is selected.
onToggle isOpen, event, source Callback function fired when the dropdown changes visibility.

Properties

Property Type Default Description
children Node   One or more MenuItem components
className String   Custom classes to be added to the <ul> tag.
header String   Adds a header to the group of MenuItems which is not focusable or selectable.

Callbacks

Property Parameters Description
onSelect eventKey, event Callback function fired when a menu item is selected.

Properties

Property Type Default Description
active Boolean   Adds an active class, aria-checked, and role attribute to the <li> tag.
children Node   Text to display inside of anchor tag or list item.
className String   Custom classes to be added to the <li> tag.
disabled Boolean false Show the item as disabled, which is not selectable.
divider Boolean false Add a horizontal divider in the menu.
eventKey String   Value passed to the onSelect callback to identify the item selected.
href String   Location to which the applicaton will navigate when item is selected.

Callbacks

Property Parameters Description
onClick event Callback function fired when the menu item is clicked.
onKeyDown event Callback function fired when the key is pressed on a menu item.
onSelect eventKey, event Callback function fired when the menu item is selected.