Dropdown API - React Magma

Dropdowns provide a portable way to display menus or lighter versions of other components. The dropdown is shown by clicking on a button or other control.

Basic Usage

The Dropdown component should contain two children: the DropdownButton component, and the DropdownContent component.

The DropdownButton is a button that handles the opening and closing of the menu.

The DropdownContent component contains the content that appears when the button is clicked. That content may contain individual menu items, represented in DropdownMenuItem components, or it may contain other markup.

When using multiple dropdowns, they should be wrapped in a ButtonGroup.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown>
      <DropdownButton>Basic Dropdown</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem>Menu item 1</DropdownMenuItem>
        <DropdownMenuItem>Menu item number two</DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

Split Button

Instead of using the DropdownButton, a DropdownSplitButton can be used instead. When using this, the larger part of the button will accept an onClick event, and only the caret icon will open and close the menu.

import React from 'react';
import {
  Dropdown,
  DropdownContent,
  DropdownMenuItem,
  DropdownSplitButton,
} from 'react-magma-dom';

export function Example() {
  function handleSplitButtonClick() {
    alert('Button Clicked!');
  }

  return (
    <Dropdown>
      <DropdownSplitButton onClick={handleSplitButtonClick}>
        Split Button
      </DropdownSplitButton>
      <DropdownContent>
        <DropdownMenuItem>Menu item 1</DropdownMenuItem>
        <DropdownMenuItem>Menu item number two</DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

Drop Direction (deprecated)

Using the dropDirection prop will change where the menu appears and the arrow direction. Options are down, up, left and right with down being default.

Deprecation note: Dropdowns now support viewport detection, so there is no need to use the dropDirection prop. The dropdown will always open where there is enough space, and the arrow will always face down.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownDropDirection,
  DropdownMenuItem,
  ButtonGroup,
} from 'react-magma-dom';

export function Example() {
  return (
    <ButtonGroup>
      <Dropdown dropDirection={DropdownDropDirection.left}>
        <DropdownButton>Drop Left</DropdownButton>
        <DropdownContent>
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item number two</DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
      <Dropdown dropDirection={DropdownDropDirection.up}>
        <DropdownButton>Drop Up</DropdownButton>
        <DropdownContent>
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item number two</DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
      <Dropdown dropDirection={DropdownDropDirection.right}>
        <DropdownButton>Drop Right</DropdownButton>
        <DropdownContent>
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item number two</DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
    </ButtonGroup>
  );
}

Alignment (deprecated)

Using the alignment prop will set the alignment of the content in relationship to the button.

The default value is start, meaning that a drop-down or a drop-up, will have the dropdown content aligned to the left side of the button, and a drop-left or a drop-right will have the content aligned to the top of the button.

The other option is end, meaning that a drop-down or a drop-up, will have the dropdown content aligned to the right side of the button, and a drop-left or a drop-right will have the content aligned to the bottom of the button.

Deprecation note: Dropdowns now support viewport detection, so there is no need to use the alignment prop.

import React from 'react';
import {
  Dropdown,
  DropdownAlignment,
  DropdownButton,
  DropdownContent,
  DropdownDropDirection,
  DropdownMenuItem,
  ButtonGroup,
} from 'react-magma-dom';

export function Example() {
  return (
    <>
      <ButtonGroup>
        <Dropdown
          alignment={DropdownAlignment.end}
          dropDirection={DropdownDropDirection.left}
        >
          <DropdownButton>Top-Aligned Drop Left</DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>

        <Dropdown
          alignment={DropdownAlignment.end}
          dropDirection={DropdownDropDirection.right}
        >
          <DropdownButton>Top-Aligned Drop Right</DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
      </ButtonGroup>

      <br />

      <ButtonGroup>
        <Dropdown
          alignment={DropdownAlignment.end}
          dropDirection={DropdownDropDirection.down}
        >
          <DropdownButton>Right-Aligned Drop Down</DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>

        <Dropdown
          alignment={DropdownAlignment.end}
          dropDirection={DropdownDropDirection.up}
        >
          <DropdownButton>Right-Aligned Drop Up</DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
      </ButtonGroup>
    </>
  );
}

Fixed Width

By default, the dropdown content will be as wide as the largest item. However, you may limit the width using the width prop, in which case items will wrap if needed. The width prop can either be a string or a number. If a number is provided, then pixels will be used for the unit.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown width="250px">
      <DropdownButton>Fixed Width</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla tellus
          turpis, finibus et bibendum eget, rhoncus ut risus. Proin nec nisi ut
          eros aliquam interdum.
        </DropdownMenuItem>
        <DropdownMenuItem>
          Nunc egestas ullamcorper finibus. Phasellus non risus id mauris
          dignissim molestie in sit amet enim. In condimentum fringilla sodales.
        </DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

Max-Height

By default, the max-height of the dropdown content is 250px. That can be changed by using the maxHeight prop. The maxHeight prop can either be a string or a number. If a number is provided, then pixels will be used for the unit.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown maxHeight="150px">
      <DropdownButton>Max-Height</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem>Menu item 1</DropdownMenuItem>
        <DropdownMenuItem>Menu item 2</DropdownMenuItem>
        <DropdownMenuItem>Menu item 3</DropdownMenuItem>
        <DropdownMenuItem>Menu item 4</DropdownMenuItem>
        <DropdownMenuItem>Menu item 5</DropdownMenuItem>
        <DropdownMenuItem>Menu item 6</DropdownMenuItem>
        <DropdownMenuItem>Menu item 7</DropdownMenuItem>
        <DropdownMenuItem>Menu item 8</DropdownMenuItem>
        <DropdownMenuItem>Menu item 9</DropdownMenuItem>
        <DropdownMenuItem>Menu item 10</DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

DropdownMenuItem

The DropdownMenuItem component can be used within the DropdownContent to indicate individual menu items, which will render as buttons. The items accept an onClick event. The disabled prop can be used on an item to disable that action. These items can be navigated by using the up and down arrow keys.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  function handleMenuItem1Click() {
    alert('Item 1 clicked');
  }

  function handleMenuItem2Click() {
    alert('Item 2 clicked');
  }

  function handleMenuItem3Click() {
    alert('Item 3 clicked');
  }

  return (
    <Dropdown>
      <DropdownButton>Dropdown Menu Items</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem onClick={handleMenuItem1Click}>
          Menu item 1
        </DropdownMenuItem>
        <DropdownMenuItem disabled onClick={handleMenuItem2Click}>
          Menu item 2
        </DropdownMenuItem>
        <DropdownMenuItem onClick={handleMenuItem3Click}>
          Menu item 3
        </DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

DropdownMenuNavItem

To render links within a dropdown, use the DropdownMenuNavItem component. It accepts a to prop, which is used as the link's href and accepts any other props that an anchor element would accept.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuNavItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown>
      <DropdownButton>Dropdown Menu Items</DropdownButton>
      <DropdownContent>
        <DropdownMenuNavItem to="http://www.google.com" target="_blank">
          Google
        </DropdownMenuNavItem>
        <DropdownMenuNavItem to="http://www.cengage.com" target="_blank">
          Cengage
        </DropdownMenuNavItem>
      </DropdownContent>
    </Dropdown>
  );
}

Expandable Menu Items

If a nested menu layout is needed within the Dropdown, the DropdownExpandableMenuGroup adds an expandable / collapsible menu structure.

The components of DropdownExpandableMenuGroup, DropdownExpandableMenuItem, DropdownExpandableMenuButton, DropdownExpandableMenuPanel, and DropdownExpandableMenuListItem necessitate the proper structure of this menu list.

Please note that only one child panel is supported from a styling standpoint.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownDivider,
  DropdownExpandableMenuGroup,
  DropdownExpandableMenuItem,
  DropdownExpandableMenuButton,
  DropdownExpandableMenuPanel,
  DropdownExpandableMenuListItem,
} from 'react-magma-dom';

import {
  RestaurantMenuIcon,
  LunchDiningIcon,
  LocalPizzaIcon,
} from 'react-magma-icons';

export function Example() {
  return (
    <Dropdown width={240}>
      <DropdownButton>Expandable Items Dropdown</DropdownButton>
      <DropdownContent>
        <DropdownExpandableMenuGroup>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton icon={<RestaurantMenuIcon />}>
              Pasta
            </DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Fresh
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Processed
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton icon={<LunchDiningIcon />}>
              Prosciutto
            </DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Domestic
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Speck
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
        </DropdownExpandableMenuGroup>
        <DropdownDivider />
        <DropdownExpandableMenuListItem icon={<LocalPizzaIcon />}>
          Pizza
        </DropdownExpandableMenuListItem>
      </DropdownContent>
    </Dropdown>
  );
}

Expandable Menu with item auto expanded

By default, the isMulti prop is true on DropdownExpandableMenuGroup, which means that the expandable dropdown will allow multiple items to be expanded at once. If you wish to limit the number of items open at once, you can set the isMulti prop to false.

The defaultIndex prop on DropdownExpandableMenuGroup uses an array of zero based indices to enable expandable groups to be automatically opened.

When the isMulti prop is false, the defaultIndex prop will take a single number, instead of an array.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownDivider,
  DropdownExpandableMenuGroup,
  DropdownExpandableMenuItem,
  DropdownExpandableMenuButton,
  DropdownExpandableMenuPanel,
  DropdownExpandableMenuListItem,
} from 'react-magma-dom';

import {
  RestaurantMenuIcon,
  LunchDiningIcon,
  LocalPizzaIcon,
} from 'react-magma-icons';

export function Example() {
  return (
    <Dropdown width={240}>
      <DropdownButton>Expandable Items Dropdown</DropdownButton>
      <DropdownContent>
        <DropdownExpandableMenuGroup defaultIndex={[0]}>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton icon={<RestaurantMenuIcon />}>
              Pasta
            </DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Fresh
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Processed
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton icon={<LunchDiningIcon />}>
              Prosciutto
            </DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Domestic
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Speck
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
        </DropdownExpandableMenuGroup>
        <DropdownDivider />
        <DropdownExpandableMenuListItem icon={<LocalPizzaIcon />}>
          Pizza
        </DropdownExpandableMenuListItem>
      </DropdownContent>
    </Dropdown>
  );
}

Text only Expandable Menu Item

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownDivider,
  DropdownExpandableMenuGroup,
  DropdownExpandableMenuItem,
  DropdownExpandableMenuButton,
  DropdownExpandableMenuPanel,
  DropdownExpandableMenuListItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown width={240}>
      <DropdownButton>Expandable Items Dropdown</DropdownButton>
      <DropdownContent>
        <DropdownExpandableMenuGroup>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton>Pasta</DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Fresh
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Processed
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
          <DropdownExpandableMenuItem>
            <DropdownExpandableMenuButton>
              Prosciutto
            </DropdownExpandableMenuButton>
            <DropdownExpandableMenuPanel>
              <DropdownExpandableMenuListItem>
                Domestic
              </DropdownExpandableMenuListItem>
              <DropdownExpandableMenuListItem>
                Speck
              </DropdownExpandableMenuListItem>
            </DropdownExpandableMenuPanel>
          </DropdownExpandableMenuItem>
        </DropdownExpandableMenuGroup>
        <DropdownDivider />
        <DropdownExpandableMenuListItem>Pizza</DropdownExpandableMenuListItem>
      </DropdownContent>
    </Dropdown>
  );
}

Custom DropdownMenuItem Wrappers

DropdownContent expects its children to be of type DropdownMenuItem, be an element in which its lowest child is of type DropdownMenuItem, or a custom component that returns a DropdownMenuItem.

For a custom component you'll receive a dropdownMenuItemProps prop that you must spread in to the DropdownMenuItem component in your renderer.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  const OptionalDropdownMenuItem = ({ toggle, dropdownMenuItemProps }) => {
    return toggle ? (
      <DropdownMenuItem {...dropdownMenuItemProps}>
        Hello There
      </DropdownMenuItem>
    ) : null;
  };

  function handleMenuItem1Click() {
    alert('Item 1 clicked');
  }

  function handleMenuItem2Click() {
    alert('Item 2 clicked');
  }

  function handleMenuItem3Click() {
    alert('Item 3 clicked');
  }

  return (
    <Dropdown>
      <DropdownButton>Dropdown Menu Items</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem onClick={handleMenuItem1Click}>
          Menu item 1
        </DropdownMenuItem>
        <OptionalDropdownMenuItem toggle onClick={handleMenuItem2Click}>
          Menu item 2
        </OptionalDropdownMenuItem>
        <div>
          <DropdownMenuItem onClick={handleMenuItem3Click}>
            Menu item 3
          </DropdownMenuItem>
        </div>
      </DropdownContent>
    </Dropdown>
  );
}

Leading Icons

The icon prop can be used to specify an icon for the DropdownMenuItem elements.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';
import { AsteriskIcon, NotificationsIcon } from 'react-magma-icons';

export function Example() {
  return (
    <Dropdown>
      <DropdownButton>Leading Icons</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem icon={<AsteriskIcon />}>Menu item 1</DropdownMenuItem>
        <DropdownMenuItem icon={<NotificationsIcon />}>
          Menu item 2
        </DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

Dropdown without Menu Items

Dropdowns can contain elements other than DropdownMenuItem components. They can be used to wrap a form, filters, or informational content.

While users may navigate between DropdownMenuItem components using up and down arrow keys, browser default keyboard behavior applies to other content.

Dropdown with Filter

import React from 'react';
import {
  Checkbox,
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownHeader,
  magma,
} from 'react-magma-dom';

export function Example() {
  const [checkedItems, setCheckedItems] = React.useState([]);

  function updateCheckedItems(e) {
    if (e.target.checked) {
      if (!checkedItems.includes(e.target.value)) {
        setCheckedItems([...checkedItems, e.target.value]);
      }
    } else if (!e.target.checked) {
      setCheckedItems(checkedItems.filter(i => i !== e.target.value));
    }
  }

  return (
    <Dropdown width="300px">
      <DropdownButton>Filter Dropdown ({checkedItems.length})</DropdownButton>
      <DropdownContent>
        <DropdownHeader id="checkboxGroup">Checkbox Group Label</DropdownHeader>
        <form
          style={{
            color: magma.colors.neutral,
            margin: 0,
            paddingLeft: magma.spaceScale.spacing05,
            paddingRight: magma.spaceScale.spacing05,
          }}
        >
          <div role="group" aria-labelledby="checkboxGroup">
            <Checkbox
              value="1"
              labelText="Option 1"
              onClick={updateCheckedItems}
            />
            <Checkbox
              value="2"
              labelText="Option 2"
              onClick={updateCheckedItems}
            />
            <Checkbox
              value="3"
              labelText="Option 3"
              onClick={updateCheckedItems}
            />
          </div>
        </form>
      </DropdownContent>
    </Dropdown>
  );
}

Dropdown with Informational Content

import React from 'react';
import {
  Checkbox,
  Dropdown,
  DropdownButton,
  DropdownContent,
  Paragraph,
  magma,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown width="300px">
      <DropdownButton>Informational Dropdown</DropdownButton>
      <DropdownContent style={{ padding: magma.spaceScale.spacing05 }}>
        <Paragraph noMargins>
          In this activity you must achieve 80% or higher to receive credit
        </Paragraph>
      </DropdownContent>
    </Dropdown>
  );
}

Custom Button

Both the DropdownButton and DropdownSplitButtoncan be customized by using any of the props that the Button component accepts. If noiconproperty is provided to theDropdownButton, the caret icon will appear.

import React from 'react';
import {
  ButtonColor,
  ButtonSize,
  ButtonGroup,
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
  DropdownSplitButton,
} from 'react-magma-dom';

export function Example() {
  return (
    <ButtonGroup>
      <Dropdown>
        <DropdownButton size={ButtonSize.small} color={ButtonColor.marketing}>
          Extra Props Example 1
        </DropdownButton>
        <DropdownContent>
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item number two</DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
      <Dropdown>
        <DropdownSplitButton
          size={ButtonSize.large}
          variant={ButtonVariant.solid}
          color={ButtonColor.danger}
          aria-label={'Custom Button Example'}
        >
          Extra Props Split
        </DropdownSplitButton>
        <DropdownContent>
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item number two</DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
    </ButtonGroup>
  );
}

Custom Icon Button

Similarly, the DropdownButton can be customized by using any of the props that the Icon Button component accepts, to create a button with an icon.

import React from 'react';
import {
  ButtonColor,
  ButtonIconPosition,
  ButtonSize,
  ButtonVariant,
  ButtonGroup,
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';
import { SettingsIcon, MenuIcon } from 'react-magma-icons';

export function Example() {
  return (
    <>
      <ButtonGroup>
        <Dropdown>
          <DropdownButton
            aria-label="Extra icon example"
            color={ButtonColor.secondary}
            size={ButtonSize.large}
            variant={ButtonVariant.link}
            icon={<SettingsIcon />}
          />
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownButton
            aria-label="Extra icon example"
            size={ButtonSize.large}
            icon={<MenuIcon />}
          />
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownButton
            variant={ButtonVariant.solid}
            size={ButtonSize.small}
            iconPosition={ButtonIconPosition.right}
            icon={<SettingsIcon />}
          >
            Icon Right with Text
          </DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
        <Dropdown>
          <DropdownButton
            variant={ButtonVariant.solid}
            size={ButtonSize.small}
            iconPosition={ButtonIconPosition.left}
            icon={<SettingsIcon />}
          >
            Icon Left with Text
          </DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item 1</DropdownMenuItem>
            <DropdownMenuItem>Menu item number two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
      </ButtonGroup>
    </>
  );
}

Breaking a Menu Into Groups

A DropdownMenu can be broken into multiple groups, by using the DropdownMenuGroup and DropdownDivider components.

The DropdownMenuGroup component accepts a header prop to be used to describe the group. The menu group div will be given a role of group and an aria-labelledbyId that corresponds with the header made internally.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownDivider,
  DropdownMenuGroup,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  return (
    <Dropdown>
      <DropdownButton>Divider and headings</DropdownButton>
      <DropdownContent>
        <DropdownMenuGroup header="Section title A">
          <DropdownMenuItem>Menu item 1</DropdownMenuItem>
          <DropdownMenuItem>Menu item 2</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownDivider />
        <DropdownMenuGroup header="Section title B">
          <DropdownMenuItem>Menu item 3</DropdownMenuItem>
          <DropdownMenuItem>Menu item 4</DropdownMenuItem>
        </DropdownMenuGroup>
        <DropdownDivider />
        <DropdownMenuGroup>
          <DropdownMenuItem>Log out</DropdownMenuItem>
        </DropdownMenuGroup>
      </DropdownContent>
    </Dropdown>
  );
}

Active Item Index

The activeIndex prop can be used to set an item within the dropdown as active. When another item is selected, that item will become active and the menu will remain open, rather than closing as usual.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  const [activeValue, setActiveValue] = React.useState<string>('two');

  function changeActiveValue(value: string) {
    setActiveValue(value);
  }

  return (
    <>
      <p>
        <strong>Active Value: </strong> <span>{activeValue}</span>
      </p>
      <Dropdown activeIndex={1}>
        <DropdownButton>Selected Item</DropdownButton>
        <DropdownContent>
          <DropdownMenuItem onClick={changeActiveValue} value="one">
            Dropdown Item 1
          </DropdownMenuItem>
          <DropdownMenuItem onClick={changeActiveValue} value="two">
            Dropdown Item 2
          </DropdownMenuItem>
          <DropdownMenuItem onClick={changeActiveValue} value="three">
            Dropdown Item 3
          </DropdownMenuItem>
        </DropdownContent>
      </Dropdown>
    </>
  );
}

Handle Focus on Close

By default the consumer is expected to handle the focusing of elements when items are clicked. If there is no new element to focus on item click you should focus the trigger button on closing of the dropdown. For this you can use a ref passed to the DropdownButton or DropdownSplitButton and focus that ref in the onClose function passed to the Dropdown component.

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
} from 'react-magma-dom';

export function Example() {
  const buttonRef = React.useRef<HTMLButtonElement>();

  function handleClose(event: React.SyntheticEvent) {
    buttonRef.current.focus();
  }

  return (
    <Dropdown onClose={handleClose}>
      <DropdownButton ref={buttonRef}>Basic Dropdown</DropdownButton>
      <DropdownContent>
        <DropdownMenuItem>Menu item 1</DropdownMenuItem>
        <DropdownMenuItem>Menu item number two</DropdownMenuItem>
      </DropdownContent>
    </Dropdown>
  );
}

Inverse

import React from 'react';
import {
  Dropdown,
  DropdownButton,
  DropdownContent,
  DropdownMenuItem,
  Card,
  CardBody,
} from 'react-magma-dom';

export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <Dropdown isInverse>
          <DropdownButton>Basic Dropdown</DropdownButton>
          <DropdownContent>
            <DropdownMenuItem>Menu item one</DropdownMenuItem>
            <DropdownMenuItem>Menu item two</DropdownMenuItem>
          </DropdownContent>
        </Dropdown>
      </CardBody>
    </Card>
  );
}

Dropdown Props

Any other props supplied will be provided to the wrapping div element.

activeIndex

Description

Index of the item that will active/selected. If none is provided, no item will appear active

Type

number

Default

-1

alignment

Deprecated

Description

Alignment of the dropdown content

Type

enum, one of:
DropdownAlignment.end
DropdownAlignment.start

Default

DropdownAlignment.start

dropDirection

Deprecated

Description

Position of the dropdown content

Type

enum, one of:
DropdownDropDirection.down
DropdownDropDirection.left
DropdownDropDirection.right
DropdownDropDirection.up

Default

DropdownDropDirection.down

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

maxHeight

Description

Max-height of dropdown content

Type

string | number

Default

250px

onClose

Description

Function called when closing the dropdown menu

Type

function

Default

onOpen

Description

Function called when opening the dropdown menu

Type

function

Default

width

Description

Width of menu

Type

string | number

Default

Width of longest menu item

Dropdown Content Props

Props supplied will be provided to the wrapping div element.

Examples may include an id, a title, event handlers or various aria attributes. It is unlikely that it will be necessary to provide additional props.

children

Required

Description

The content of the component

Type

ReactNode | undefined

Default

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

Dropdown Header Props

Any other props supplied will be provided to the wrapping div element.

children

Required

Description

The content of the component

Type

ReactNode | undefined

Default

Dropdown Menu Group

Any other props supplied will be provided to the wrapping div element.

children

Required

Description

The content of the component

Type

ReactNode | undefined

Default

header

Description

Header text to use for the menu group

Type

React.ReactNode

Default

Dropdown Menu Item

Any other props supplied will be provided to the wrapping li element.

disabled

Description

If true, item will be disabled; it will appear dimmed and onClick event (or any other events) will not fire

Type

boolean

Default

false

icon

Description

Leading icon for the menu item

Type

ReactElement

Default

onClick

Description

Action that fires when the menu item is clicked. If the menuitem also has a value prop, the value will be passed to the onClick handler

Type

function

Default

value

Description

Value of the component, gets passed to the onClick event

Type

string | number

Default

Dropdown Button Props

DropdownButton and the DropdownSplitButton accept the same props as the Button component.

children

Required

Description

The content of the component

Type

node

Default

color

Description

The color of the button, indicating its function in the UI

Type

enum, one of:
ButtonColor.primary
ButtonColor.secondary
ButtonColor.danger
ButtonColor.marketing

Default

primary

isFullWidth

Description

If true, the button will take up the full width of its container

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

shape

Description

Defines the border radius

Type

enum, one of:
ButtonShape.fill
ButtonShape.leftCap
ButtonShape.rightCap

Default

fill

size

Description

The relative size of the button

Type

enum, one of:
ButtonSize.large
ButtonSize.medium
ButtonSize.small

Default

medium

textTransform

Description

Determines whether the button appears in all-caps

Type

enum, one of:
ButtonTextTransform.uppercase
ButtonTextTransform.none

Default

uppercase

type

Description

The type attribute of the button

Type

enum, one of:
ButtonType.button
ButtonType.submit
ButtonType.reset

Default

button

variant

Description

The variant of the button

Type

enum, one of:
ButtonVariant.solid
ButtonVariant.link

Default

solid

The DropdownButton can also accept an icon property, as in the Icon Button component.

aria-label

Description

The text the screen reader will announce. Required for icon-only buttons

Type

string

Default

children

Description

The content of the component. If no children are provided, the button will render in an icon only style

Type

node

Default

color

Description

The color of the button, indicating its function in the UI

Type

enum, one of:
ButtonColor.primary
ButtonColor.secondary
ButtonColor.danger
ButtonColor.marketing

Default

primary

disabled

Description

If true, element is disabled

Type

boolean

Default

false

icon

Required

Description

Icon to display within the component

Type

React Element

Default

iconPosition

Description

Position within the button for the icon to appear

Type

enum, one of:
ButtonIconPosition.left
ButtonIconPosition.right

Default

right

isFullWidth

Description

If true, the button will take up the full width of its container

Type

boolean

Default

false

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

shape

Description

Defines the border radius

Type

enum, one of:
ButtonShape.fill
ButtonShape.leftCap
ButtonShape.rightCap
ButtonShape.round

Default

round

size

Description

The relative size of the button

Type

enum, one of:
ButtonSize.large
ButtonSize.medium
ButtonSize.small

Default

medium

textTransform

Description

Determines whether the button appears in all-caps

Type

enum, one of:
ButtonTextTransform.uppercase
ButtonTextTransform.none

Default

uppercase

type

Description

The type attribute of the button

Type

enum, one of:
ButtonType.button
ButtonType.submit
ButtonType.reset

Default

button

variant

Description

The variant of the button

Type

enum, one of:
ButtonVariant.solid
ButtonVariant.link

Default

solid

Dropdown Menu Nav Item

Any other props supplied will be provided to the wrapping a element.

icon

Description

Leading icon for the menu item

Type

ReactElement

Default

Required

Description

The href value of the link

Type

string

Default

Dropdown Expandable Menu Panel Props

Any other props supplied will be provided to the wrapping div element.

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

testId

Type

string

Default

Dropdown Expandable Menu Button Props

Any other props supplied will be provided to the wrapping div element.

icon

Type

ReactElement

Default

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

testId

Type

string

Default

Dropdown Expandable Menu Item Props

Any other props supplied will be provided to the wrapping div element.

disabled

Description

If true, item will be disabled; it will appear dimmed and onClick event (or any other events) will not fire

Type

boolean

Default

false

isDisabled

Type

boolean

Default

Dropdown Expandable Menu List Item Props

Any other props supplied will be provided to the wrapping div element.

disabled

Type

boolean

Default

testId

Type

string

Default

Design

Components

Patterns

Dropdown

Basic Usage

Split Button

Drop Direction (deprecated)

Alignment (deprecated)

Fixed Width

Max-Height

DropdownMenuItem

DropdownMenuNavItem

Expandable Menu Items

Expandable Menu with item auto expanded

Text only Expandable Menu Item

Custom DropdownMenuItem Wrappers

Leading Icons

Dropdown without Menu Items

Dropdown with Filter

Dropdown with Informational Content

Custom Button

Custom Icon Button

Breaking a Menu Into Groups

Active Item Index

Handle Focus on Close

Inverse

Dropdown Props

Dropdown Content Props

Dropdown Header Props

Dropdown Menu Group

Dropdown Menu Item

Dropdown Button Props

Dropdown Menu Nav Item

Dropdown Expandable Menu Panel Props

Dropdown Expandable Menu Button Props

Dropdown Expandable Menu Item Props

Dropdown Expandable Menu List Item Props