OLYSENSE Design System

When dropdowns are used with menus , you can listen for the sense-select event to determine which menu item was selected. The menu item element will be exposed in event.detail.item. You can set value props to make it easier to identify commands.

<div class="dropdown-selection">
  <ods-dropdown>
    <ods-button slot="trigger" caret>Edit</ods-button>
    <ods-menu>
      <ods-menu-item value="cut">Cut</ods-menu-item>
      <ods-menu-item value="copy">Copy</ods-menu-item>
      <ods-menu-item value="paste">Paste</ods-menu-item>
    </ods-menu>
  </ods-dropdown>
</div>

<script>
  const container = document.querySelector('.dropdown-selection');
  const dropdown = container.querySelector('ods-dropdown');

  dropdown.addEventListener('ods-select', event => {
    const selectedItem = event.detail.item;
    console.log(selectedItem.value);
  });
</script>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';

const Example = () => {
  function handleSelect(event: any) {
    const selectedItem = event.detail.item;
    console.log(selectedItem.value);
  }

  return (
    <OdsDropdown>
      <OdsButton slot="trigger" caret>
        Edit
      </OdsButton>
      <OdsMenu onOdsSelect={handleSelect}>
        <OdsMenuItem value="cut">Cut</OdsMenuItem>
        <OdsMenuItem value="copy">Copy</OdsMenuItem>
        <OdsMenuItem value="paste">Paste</OdsMenuItem>
      </OdsMenu>
    </OdsDropdown>
  );
}

export default Example;

Dropdowns are designed to work well with menus to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. color picker). The API gives you complete control over showing, hiding, and positioning the panel.

<ods-dropdown>
  <ods-button slot="trigger">Edit <ods-icon name="chevron-down" slot='suffix'></ods-icon></ods-button>
  <ods-menu>
    <ods-menu-item>Option 1</ods-menu-item>
    <ods-menu-item>Option 2</ods-menu-item>
    <ods-menu-item>Option 3</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item type="checkbox" checked>Checkbox</ods-menu-item>
    <ods-menu-item disabled>Disabled</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item>
      <span>Prefix Icon</span>
      <ods-icon slot="prefix" name="frame"></ods-icon>
    </ods-menu-item>
    <ods-menu-item>
      <span>Suffix Icon</span>
      <ods-icon slot="suffix" name="download"></ods-icon>
    </ods-menu-item>
  </ods-menu>
</ods-dropdown>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';
import { OdsDivider } from '@ods/components/react.divider';
import { OdsIcon } from '@ods/components/react.icon';

const Example = () => {
  return (
    <OdsDropdown>
      <OdsButton slot="trigger">Edit <OdsIcon name="chevron-down" slot='suffix'></OdsIcon></OdsButton>
      <OdsMenu>
        <OdsMenuItem>Option 1</OdsMenuItem>
        <OdsMenuItem>Option 2</OdsMenuItem>
        <OdsMenuItem>Option 3</OdsMenuItem>
        <OdsDivider></OdsDivider>
        <OdsMenuItem type="checkbox" checked>Checkbox</OdsMenuItem>
        <OdsMenuItem disabled>Disabled</OdsMenuItem>
        <OdsDivider></OdsDivider>
        <OdsMenuItem>
          <span>Prefix Icon</span>
          <OdsIcon slot="prefix" name="frame"></OdsIcon>
        </OdsMenuItem>
        <OdsMenuItem>
          <span>Suffix Icon</span>
          <OdsIcon slot="suffix" name="download"></OdsIcon>
        </OdsMenuItem>
      </OdsMenu>
    </OdsDropdown>
  )
}

export default Example;

The preferred placement of the dropdown can be set with the placement attribute. Note that the actual position may vary to ensure the panel remains in the viewport.

Edit

Cut

Copy

Paste

Find

Replace

<ods-dropdown placement="top-start">
  <ods-button slot="trigger">Edit <ods-icon name="chevron-down" slot='suffix'></ods-icon></ods-button>
  <ods-menu>
    <ods-menu-item>Cut</ods-menu-item>
    <ods-menu-item>Copy</ods-menu-item>
    <ods-menu-item>Paste</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item>Find</ods-menu-item>
    <ods-menu-item>Replace</ods-menu-item>
  </ods-menu>
</ods-dropdown>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';
import { OdsDivider } from '@ods/components/react.divider';
import { OdsIcon } from '@ods/components/react.icon';

const Example = () => {
  return (
    <OdsDropdown placement="top-start">
    <OdsButton slot="trigger">Edit <OdsIcon name="chevron-down" slot='suffix'></OdsIcon></OdsButton>
    <OdsMenu>
      <OdsMenuItem>Cut</OdsMenuItem>
      <OdsMenuItem>Copy</OdsMenuItem>
      <OdsMenuItem>Paste</OdsMenuItem>
      <OdsDivider></OdsDivider>
      <OdsMenuItem>Find</OdsMenuItem>
      <OdsMenuItem>Replace</OdsMenuItem>
    </OdsMenu>
  </OdsDropdown>
  )
}

export default Example;

The distance from the panel to the trigger can be customized using the distance attribute. This value is specified in pixels.

Edit

Cut

Copy

Paste

Find

Replace

<ods-dropdown distance="30">
  <ods-button slot="trigger">Edit <ods-icon name="chevron-down" slot='suffix'></ods-icon></ods-button>
  <ods-menu>
    <ods-menu-item>Cut</ods-menu-item>
    <ods-menu-item>Copy</ods-menu-item>
    <ods-menu-item>Paste</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item>Find</ods-menu-item>
    <ods-menu-item>Replace</ods-menu-item>
  </ods-menu>
</ods-dropdown>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';
import { OdsDivider } from '@ods/components/react.divider';
import { OdsIcon } from '@ods/components/react.icon';

const Example = () => {
  return (
    <OdsDropdown skidding={30}>
      <OdsButton slot="trigger">Edit <OdsIcon name="chevron-down" slot='suffix'></OdsIcon></OdsButton>
      <OdsMenu>
        <OdsMenuItem>Cut</OdsMenuItem>
        <OdsMenuItem>Copy</OdsMenuItem>
        <OdsMenuItem>Paste</OdsMenuItem>
        <OdsDivider></OdsDivider>
        <OdsMenuItem>Find</OdsMenuItem>
        <OdsMenuItem>Replace</OdsMenuItem>
      </OdsMenu>
    </OdsDropdown>
  )
}

export default Example;

The offset of the panel along the trigger can be customized using the skidding attribute. This value is specified in pixels.

Edit

Cut

Copy

Paste

Find

Replace

<ods-dropdown skidding="30">
  <ods-button slot="trigger">Edit <ods-icon name="chevron-down" slot='suffix'></ods-icon></ods-button>
  <ods-menu>
    <ods-menu-item>Cut</ods-menu-item>
    <ods-menu-item>Copy</ods-menu-item>
    <ods-menu-item>Paste</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item>Find</ods-menu-item>
    <ods-menu-item>Replace</ods-menu-item>
  </ods-menu>
</ods-dropdown>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';
import { OdsDivider } from '@ods/components/react.divider';
import { OdsIcon } from '@ods/components/react.icon';

const Example = () => {
  return (
    <OdsDropdown skidding={30}>
      <OdsButton slot="trigger">Edit <OdsIcon name="chevron-down" slot='suffix'></OdsIcon></OdsButton>
      <OdsMenu>
        <OdsMenuItem>Cut</OdsMenuItem>
        <OdsMenuItem>Copy</OdsMenuItem>
        <OdsMenuItem>Paste</OdsMenuItem>
        <OdsDivider></OdsDivider>
        <OdsMenuItem>Find</OdsMenuItem>
        <OdsMenuItem>Replace</OdsMenuItem>
      </OdsMenu>
    </OdsDropdown>
  )
}

export default Example;

When dropdowns are used with menus, you can listen for the ods-select event to determine which menu item was selected. The menu item element will be exposed in event.detail.item. If you need to trigger an event on the dropdown itself, you can see dropdown specific events here .

<ods-dropdown id="dropdown-example">
  <ods-button slot="trigger">Edit <ods-icon name="chevron-down" slot='suffix'></ods-icon></ods-button>
  <ods-menu>
    <ods-menu-item value="cut">Cut</ods-menu-item>
    <ods-menu-item value="copy">Copy</ods-menu-item>
    <ods-menu-item value="paste">Paste</ods-menu-item>
    <ods-divider></ods-divider>
    <ods-menu-item value="find">Find</ods-menu-item>
    <ods-menu-item value="replace">Replace</ods-menu-item>
  </ods-menu>
</ods-dropdown>

<script>
  const dropdownExample = document.getElementById('dropdown-example');

  const onSelectHandler = (event) => {
    const selectedItem = event.detail.item;

    alert(`Selected item is ${selectedItem.value}`);
  };

  dropdownExample.addEventListener('ods-select', event => onSelectHandler(event));
</script>

import { OdsDropdown } from '@ods/components/react.dropdown';
import { OdsButton } from '@ods/components/react.button';
import { OdsMenu } from '@ods/components/react.menu';
import { OdsMenuItem } from '@ods/components/react.menu-item';
import { OdsDivider } from '@ods/components/react.divider';
import { OdsIcon } from '@ods/components/react.icon';
import { OdsSelectEvent } from '@ods/components/react';

export const Example = () => {
  const onSelectHandler = (event: OdsSelectEvent) => {
    const selectedItem = event.detail.item;

    alert(`Selected item is ${selectedItem.value}`);
  };

  return (
    <OdsDropdown>
      <OdsButton slot="trigger">Edit <OdsIcon name="chevron-down" slot='suffix'></OdsIcon></OdsButton>
      <OdsMenu onOdsSelect={onSelectHandler}>
        <OdsMenuItem value='cut'>Cut</OdsMenuItem>
        <OdsMenuItem value='copy'>Copy</OdsMenuItem>
        <OdsMenuItem value='paste'>Paste</OdsMenuItem>
        <OdsDivider></OdsDivider>
        <OdsMenuItem value='find'>Find</OdsMenuItem>
        <OdsMenuItem value='replace'>Replace</OdsMenuItem>
      </OdsMenu>
    </OdsDropdown>
  )
}

export default Example;

Importing

import '@ods/components/web.dropdown';

Note: You only need to import a web component once in your code, as it registers itself globally when defined, allowing you to use it anywhere within your application without needing to re-import it each time you want to use the component.

Slots

Name	Description
(default)	The dropdown's main content.
trigger	The dropdown's trigger, usually a `<ods-button>` element.

Properties

Please note, both DOM properties and HTML attributes are shown in the table below. Unless otherwise specified, the property and attribute names are identical.

Property/Attribute	Type	Default
open	boolean	false
placement	\| 'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'right' \| 'right-start' \| 'right-end' \| 'left' \| 'left-start' \| 'left-end'	'bottom-start'
disabled	boolean	false
stayOpenOnSelect stay-open-on-select	boolean	false
distance	number	0
skidding	number	0
hoist	boolean	false
sync	'width' \| 'height' \| 'both' \| undefined	undefined

Events

React Event	Description	Event Detail
ods-show	Emitted when the dropdown opens.	--
ods-after-show	Emitted after the dropdown opens and all animations are complete.	--
ods-hide	Emitted when the dropdown closes.	--
ods-after-hide	Emitted after the dropdown closes and all animations are complete.	--

Methods

Name	Description	Arguments
show()	Shows the dropdown panel.	--
hide()	Hides the dropdown panel	--
reposition()	Instructs the dropdown menu to reposition. Useful when the position or size of the trigger changes when the menu is activated.	--

Parts

Name	Description
base	The component's base wrapper.
trigger	The container that wraps the trigger.
panel	The panel that gets shown when the dropdown is open.

Dependencies

This component automatically imports the following dependencies.

ods-popup

Usage

This section includes guidelines for designers and developers about the usage of this component in different contexts.

Use Dropdowns when you have more than 2 additional actions for the given ui element
Organize Dropdown content logically, with descedning hierarchy of items
Use for More Menus, triggered by a 3-dot menu icon button
Use in Application Bar for User Menu and Application Switcher

Use Dropdowns in Forms - use a Select instead
Put primary actions under a Dropdown menu - use Buttons for primary actions, and Dropdown for overflow actions
Nest mutliple additional components under a Dropdown
Use prefix icons unless absolutely necessary - they conflict with the included down chevron suffix icon

Content Guidelines

Guideline	Good Example	Bad Example
Use action-led terms in the button trigger	Create, Save, Edit, Choose	User, More
Brevity is ideal - eliminate unnecessary words	Choose Language	Choose Your Language
Use Sentence case	Select user	Select User

Dropdown

Examples

Getting the Selected Item

In Menus

Placement

Distance

Skidding

Handling An Event

Importing

Slots

Properties

Events

Methods

Parts

Dependencies

Usage

Do

Dont

Content Guidelines