Guides
Get started Component definition Designing custom elements Development best practices
Styles
Colors Typography Spacing Shadows Radii
Components
Avatar Button Checkbox ColorPicker Dropdown FormField Icon IconButton IconTile Illustration Indicator Link List Logo Menu Modal NotificationBar Pill Radio Select Skeleton Switch Tabs Text Textarea TextButton TextInput Typeahead Toast Tooltip
Loaders
Loader LogoLoader EllipsesLoader WaveformLoader
Layout
Align Arrange Backdrop Container ErrorContainer Popover Spacer Split
Icons
Icon set
Illustrations
Illustration set
Patterns
Disabled styles Errors Forms Discovery Plan upgrade Settings
Utilities
CSS utilities CSS variables Responsive
Playground
Layout recipes Showcase

Dropdown (deprecated)

Deprecated

This component is deprecated. Please use @atlaskit/dropdown-menu

Usage

import { Dropdown } from '@loomhq/lens'

<Dropdown
  triggerCallback={buttonProps => <div tabIndex="0" {...buttonProps}>Simple trigger</div>}
  options={[
    {
      title: 'Share',
      icon: <SvgUsersAdd />,
      onClick: () => (),
      disabled: false,
    },
  ]}
/>

Screen readers should accurately 'read' the text contents of the custom node you return from the callback you pass to trigger as the label for the Dropdown element. However, you can explicitly pass a label string to ariaMenuName to explicitly label the element in case screen readers are not behaving as expected.

<Arrange gap="large">
  <Dropdown
    ariaMenuName="Button with label override"
    triggerCallback={buttonProps => {
      return (
        <Arrange tabIndex="0" {...buttonProps}>
          <Text fontWeight="bold">This label is invisible to screen readers</Text>
          <Icon icon={<SvgChevronDown />} />
        </Arrange>
      )
    }}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
</Arrange>

<Arrange gap="large">
  <Dropdown
    ariaMenuName="Button with label override"
    triggerCallback={buttonProps => {
      return (
        <Arrange tabIndex="0" {...buttonProps}>
          <Text fontWeight="bold">This label is invisible to screen readers</Text>
          <Icon icon={<SvgChevronDown />} />
        </Arrange>
      )
    }}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
</Arrange>

Trigger

triggerCallback

A callback function that returns a custom node. The Dropdown component will pass the necessary ARIA attributes to allow screen readers to properly 'read' the custom node returned by your callback.

Providing this prop will override any custom node passed to trigger.

trigger (deprecated - use triggerCallback instead)

Trigger can be any custom node. If the trigger is not a button make sure to add a tabindex attribute to it.

Note on deprecation: This approach is not a11y compliant, as screen readers cannot properly 'read' the dropdown options. Using a screen reader, you can test the buttons below. Only the first should have its menu items read.

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => {
      return (
        <Arrange tabIndex="0" {...buttonProps}>
          <Text fontWeight="bold">ARIA compliant trigger</Text>
          <Icon icon={<SvgChevronDown />} />
        </Arrange>
      )
    }}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<div tabIndex="0">Simple trigger</div>}
    options={[
      { title: 'Share', onClick: () => alert('hi'), },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={
      <Arrange tabIndex="0">
        <Text fontWeight="bold">Trigger with icon</Text>
        <Icon icon={<SvgChevronDown />} />
      </Arrange>
    }
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<Button>Button trigger</Button>}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<IconButton altText="dropdown" icon={<SvgChevronDown />} />}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
</Arrange>

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => {
      return (
        <Arrange tabIndex="0" {...buttonProps}>
          <Text fontWeight="bold">ARIA compliant trigger</Text>
          <Icon icon={<SvgChevronDown />} />
        </Arrange>
      )
    }}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<div tabIndex="0">Simple trigger</div>}
    options={[
      { title: 'Share', onClick: () => alert('hi'), },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={
      <Arrange tabIndex="0">
        <Text fontWeight="bold">Trigger with icon</Text>
        <Icon icon={<SvgChevronDown />} />
      </Arrange>
    }
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<Button>Button trigger</Button>}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
  <Dropdown
    trigger={<IconButton altText="dropdown" icon={<SvgChevronDown />} />}
    options={[
      { title: 'Share' },
      { title: 'Archive' },
      { title: 'Disabled', disabled: true },
    ]}
  />
</Arrange>

Menu can be positoned on the left or right side relative to the trigger.

<Arrange gap="medium" columns={['1fr', '1fr']}>
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on left</Button>}
    menuPosition="left"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on right</Button>}
    menuPosition="right"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on top left</Button>}
    menuPosition="topLeft"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on top right</Button>}
    menuPosition="topRight"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => (
      <Button {...buttonProps}>Trigger on left side</Button>
    )}
    triggerOffset={8}
    menuPosition="leftSide"
    options={[{ title: 'Share' }, { title: 'Archive' }]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on right side</Button>}
    triggerOffset={-78}
    menuPosition="rightSide"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
</Arrange>

<Arrange gap="medium" columns={['1fr', '1fr']}>
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on left</Button>}
    menuPosition="left"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on right</Button>}
    menuPosition="right"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on top left</Button>}
    menuPosition="topLeft"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on top right</Button>}
    menuPosition="topRight"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => (
      <Button {...buttonProps}>Trigger on left side</Button>
    )}
    triggerOffset={8}
    menuPosition="leftSide"
    options={[{ title: 'Share' }, { title: 'Archive' }]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger on right side</Button>}
    triggerOffset={-78}
    menuPosition="rightSide"
    options={[
      { title: 'Share' },
      { title: 'Archive' },
    ]}
  />
</Arrange>

With icons

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
  options={[
    { title: 'Share ' + demoText.long, icon: <SvgUsersAdd /> },
    { title: 'Archive', icon: <SvgArchive /> },
    { title: 'Disabled', icon: <SvgTrash />, disabled: true }
  ]}
/>

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
  options={[
    { title: 'Share ' + demoText.long, icon: <SvgUsersAdd /> },
    { title: 'Archive', icon: <SvgArchive /> },
    { title: 'Disabled', icon: <SvgTrash />, disabled: true }
  ]}
/>

See the Icon set.

With divider

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
  options={[
    { title: 'Share ' },
    { title: 'Archive', },
    { title: 'Download', hasDivider: true }
  ]}
/>

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
  options={[
    { title: 'Share ' },
    { title: 'Archive', },
    { title: 'Download', hasDivider: true }
  ]}
/>

Min and max width

<Arrange gap="medium">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>With min width</Button>}
    menuMinWidth={10}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'C' }
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>With max width</Button>}
    menuMaxWidth={56}
    options={[
      { title: demoText.long },
      { title: demoText.short },
      { title: demoText.title }
    ]}
  />
</Arrange>

<Arrange gap="medium">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>With min width</Button>}
    menuMinWidth={10}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'C' }
    ]}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>With max width</Button>}
    menuMaxWidth={56}
    options={[
      { title: demoText.long },
      { title: demoText.short },
      { title: demoText.title }
    ]}
  />
</Arrange>

Max height

<Arrange gap="medium">
  <Dropdown
    menuMaxHeight={24}
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
    options={demoText.ordinals.map((ordinal) => {
      return { title: ordinal }
    })}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
    options={demoText.ordinals.map((ordinal) => {
      return { title: ordinal }
    })}
  />
</Arrange>

<Arrange gap="medium">
  <Dropdown
    menuMaxHeight={24}
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
    options={demoText.ordinals.map((ordinal) => {
      return { title: ordinal }
    })}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
    options={demoText.ordinals.map((ordinal) => {
      return { title: ordinal }
    })}
  />
</Arrange>

Container

Specify where it's going to be rendered in the DOM, this is especially useful when working with Shadow DOM.

<Dropdown
  container={() => document.querySelector("#renderContainer")}
  triggerCallback={buttonProps => <Button {...buttonProps}>Trigger</Button>}
  options={[
    { title: 'A' },
    { title: 'B' },
    { title: 'C' }
  ]}
/>

Search

For dropdowns with many options that make it difficult to find the intended value, a search input can be added. By default, the option values are filtered on the inputted value using a loose includes pattern.

With string options

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Contains Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'AB' },
      { title: 'BA' },
      { title: 'Aa' },
      { title: 'AA' },
      { title: 'Bb' },
      { title: 'BB' },
      { title: 'ABC' },
      { title: 'ACB' },
      { title: 'BAC' },
      { title: 'BCA' },
      { title: 'CAB' },
      { title: 'CBA' },
      { title: 'a' },
      { title: 'b' },
    ]}
    search={{
      searchPlaceholder: 'Search with includes...',
      searchType: 'contains',
    }}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Starts With Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'AB' },
      { title: 'BA' },
      { title: 'Aa' },
      { title: 'AA' },
      { title: 'Bb' },
      { title: 'BB' },
      { title: 'ABC' },
      { title: 'ACB' },
      { title: 'BAC' },
      { title: 'BCA' },
      { title: 'CAB' },
      { title: 'CBA' },
      { title: 'a' },
      { title: 'b' },
    ]}
    search={{
      searchPlaceholder: 'Search with starts with...',
      searchType: 'startsWith',
    }}
  />
</Arrange>

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Contains Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'AB' },
      { title: 'BA' },
      { title: 'Aa' },
      { title: 'AA' },
      { title: 'Bb' },
      { title: 'BB' },
      { title: 'ABC' },
      { title: 'ACB' },
      { title: 'BAC' },
      { title: 'BCA' },
      { title: 'CAB' },
      { title: 'CBA' },
      { title: 'a' },
      { title: 'b' },
    ]}
    search={{
      searchPlaceholder: 'Search with includes...',
      searchType: 'contains',
    }}
  />
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Starts With Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: 'A' },
      { title: 'B' },
      { title: 'AB' },
      { title: 'BA' },
      { title: 'Aa' },
      { title: 'AA' },
      { title: 'Bb' },
      { title: 'BB' },
      { title: 'ABC' },
      { title: 'ACB' },
      { title: 'BAC' },
      { title: 'BCA' },
      { title: 'CAB' },
      { title: 'CBA' },
      { title: 'a' },
      { title: 'b' },
    ]}
    search={{
      searchPlaceholder: 'Search with starts with...',
      searchType: 'startsWith',
    }}
  />
</Arrange>

With ReactElement options

For options that implement a ReactElement as the title of the options property, the element properties must be joined with React.PropsWithChildren or have the children property. Furthermore, the searchable value of the element must be included as a child of the element to ensure its value can be parsed.

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Element Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: <div>A</div> },
      { title: <div>B</div> },
      { title: <div>AB</div> },
      { title: <div>BA</div> },
      { title: <div>Aa</div> },
      { title: <div>AA</div> },
      { title: <div>Bb</div> },
      { title: <div>BB</div> },
      { title: <div>ABC</div> },
      { title: <div>ACB</div> },
      { title: <div>BAC</div> },
      { title: <div>BCA</div> },
      { title: <div>CAB</div> },
      { title: <div>CBA</div> },
      { title: <div>a</div> },
      { title: <div>b</div> },
    ]}
    search={{
      searchPlaceholder: 'Search with element options...',
    }}
  />
</Arrange>

<Arrange gap="large">
  <Dropdown
    triggerCallback={buttonProps => <Button {...buttonProps}>Element Search</Button>}
    menuMaxHeight={42}
    options={[
      { title: <div>A</div> },
      { title: <div>B</div> },
      { title: <div>AB</div> },
      { title: <div>BA</div> },
      { title: <div>Aa</div> },
      { title: <div>AA</div> },
      { title: <div>Bb</div> },
      { title: <div>BB</div> },
      { title: <div>ABC</div> },
      { title: <div>ACB</div> },
      { title: <div>BAC</div> },
      { title: <div>BCA</div> },
      { title: <div>CAB</div> },
      { title: <div>CBA</div> },
      { title: <div>a</div> },
      { title: <div>b</div> },
    ]}
    search={{
      searchPlaceholder: 'Search with element options...',
    }}
  />
</Arrange>

onOuterClick callback

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>console.log on change</Button>}
  onOuterClick={() => console.log('onOuterClick')}
  options={[
    { title: 'A' },
    { title: 'B' },
  ]}
/>

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>console.log on change</Button>}
  onOuterClick={() => console.log('onOuterClick')}
  options={[
    { title: 'A' },
    { title: 'B' },
  ]}
/>

onOpenChange callback

Callback that provides the isOpen value when dropdown opens or closes

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>console.log on change</Button>}
  onOpenChange={newState => console.log(newState)}
  options={[
    { title: 'A' },
    { title: 'B' },
  ]}
/>

<Dropdown
  triggerCallback={buttonProps => <Button {...buttonProps}>console.log on change</Button>}
  onOpenChange={newState => console.log(newState)}
  options={[
    { title: 'A' },
    { title: 'B' },
  ]}
/>

Props

name

type

default

menuPosition

'left'

menuZIndex

number

1100

menuMinWidth

number | string

menuMaxWidth

number | string

triggerOffset

number

ariaMenuName

string

options

OptionsObject[]

isOpen

boolean

menuMaxHeight

number | string

container

HTMLElement | (() => HTMLElement) | string

onOuterClick

() => void

onOpenChange

(isOpen: boolean) => void

{ searchPlaceholder: string; searchType?: 'contains' | 'startsWith'; }

role

React.AriaRole

menuItemRole

React.AriaRole

Guides

Styles

Components

Loaders

Layout

Icons

Illustrations

Patterns

Utilities

Playground

Dropdown (deprecated)

Deprecated

Usage

ARIA Menu Name

Trigger

triggerCallback

trigger (deprecated - use triggerCallback instead)

Menu position

With icons

With divider

Menu size

Min and max width

Max height

Container

Search

With string options

With ReactElement options

onOuterClick callback

onOpenChange callback

Props