Dropdown

Dropdowns allow users to access a list of multiple actions. A common use-case for Dropdowns is to build context menus.

A Dropdown should contain at least one DropdownList, and multiple DropdownListItem components to represent each action.

Table of contents

• How to use Dropdowns
• Code examples
• Content recommendations
• Accessibility

How to use Dropdowns

• If there is a single action to display, use TextLink or Button instead
• Use lists and titles to group similar actions
• Use a single TextLink at the bottom of the list for an action that is considerably different than the rest

Code examples

// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
Hide source

Dropdown with a title – Use a title to clarify the purpose of a dropdown.

// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with a title
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem isTitle>Dropdown title</DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with a title
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem isTitle>Dropdown title</DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
Hide source

Dropdown with multiple DropdownLists – Use multiple DropdownLists to group actions together. A DropdownList can contain a border to visually separating these lists.

// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with multiple DropdownLists
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
      <DropdownList border="top">
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with multiple DropdownLists
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
      <DropdownList border="top">
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 1
        </DropdownListItem>
        <DropdownListItem onClick={() => {}}>
          Dropdown list item 2
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
Hide source

Dropdown with links – DropdownListItems can also contain TextLinks. These are often used to highlight related actions to the content of the DropdownList.

// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      key={Date.now()} // Force Reinit
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with links
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>Kitten</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Puppy</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Piglet</DropdownListItem>
      </DropdownList>
      <DropdownList border="top">
        <DropdownListItem>
          <TextLink icon="Plus">Add a cute animal</TextLink>
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      key={Date.now()} // Force Reinit
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with links
        </Button>
      }
    >
      <DropdownList>
        <DropdownListItem onClick={() => {}}>Kitten</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Puppy</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Piglet</DropdownListItem>
      </DropdownList>
      <DropdownList border="top">
        <DropdownListItem>
          <TextLink icon="Plus">Add a cute animal</TextLink>
        </DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
Hide source

Dropdown with max height – DropdownLists can have a max height to limit the height of the dropdown and introduce scrolling. This should be used when dropdowns need to contain a lot of data.

// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      key={Date.now()} // Force Reinit
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with max height
        </Button>
      }
    >
      <DropdownList maxHeight={175}>
        <DropdownListItem onClick={() => {}}>Item 1</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 2</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 3</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 4</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 5</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 6</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 7</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 8</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 9</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 10</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 11</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 12</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 13</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 14</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 15</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 16</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 17</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 18</DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
// import { Button, Dropdown, DropdownList, DropdownListItem } from '@contentful/forma-36-react-components';

function DropdownExample() {
  const [isOpen, setOpen] = React.useState(false);
  return (
    <Dropdown
      isOpen={isOpen}
      onClose={() => setOpen(false)}
      key={Date.now()} // Force Reinit
      toggleElement={
        <Button
          size="small"
          buttonType="muted"
          indicateDropdown
          onClick={() => setOpen(!isOpen)}
        >
          Trigger Dropdown with max height
        </Button>
      }
    >
      <DropdownList maxHeight={175}>
        <DropdownListItem onClick={() => {}}>Item 1</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 2</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 3</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 4</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 5</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 6</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 7</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 8</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 9</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 10</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 11</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 12</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 13</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 14</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 15</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 16</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 17</DropdownListItem>
        <DropdownListItem onClick={() => {}}>Item 18</DropdownListItem>
      </DropdownList>
    </Dropdown>
  );
}
Hide source

Content recommendations:

• To make Dropdown action-oriented, use a verb. For example, "Add field", not "New field"
• Use clear and succinct copy

Accessibility

• Missing