monday-ui-react-core/src/components/Dropdown/__stories__/Dropdown.mdx

Official monday.com UI resources for application development in React.js

import { Meta } from "@storybook/blocks";
import {
  COMBOBOX,
  MENU,
  SPLIT_BUTTON
} from "../../../storybook/components/related-components/component-description-map";
import { Dropdown } from "../../index";
import * as DropdownStories from "./Dropdown.stories";
import { TipDevTipPopover } from "./Dropdown.stories.helpers";

<Meta of={DropdownStories} />

# Dropdown

- [Overview](#overview)
- [Props](#props)
- [Usage](#usage)
- [Variants](#variants)
- [Do’s and don’ts](#dos-and-donts)
- [Use cases and examples](#use-cases-and-examples)
- [Related components](#related-components)
- [Feedback](#feedback)

## Overview

Dropdown present a list of options from which a user can select one or several.

<Canvas of={DropdownStories.Overview} />

## Props

<PropsTable />

## Usage

<UsageGuidelines
  guidelines={[
    "Dropdown menus are typically used when you have 5-8 items to choose from. They're used for navigation or command menus, where an action is initiated based on the selection.",
    "Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown also use the same size text inputs, buttons, and so on.",
    "Avoid having multiple lines of text in a dropdown. If the text is too long for one line, add an ellipsis (…).",
    "When the menu is open, each option in the menu should be the same height as the field.",
    "When organizing dropdown menu items, sort the list in a logical order by putting the most selected option at the top."
  ]}
/>

## Variants

### Sizes

There are three sizes available: Small, Medium, and Large

<Canvas of={DropdownStories.Sizes} />

### Disabled

<Canvas of={DropdownStories.Disabled} />

### Readonly

<Canvas of={DropdownStories.Readonly} />

### RTL

<Canvas of={DropdownStories.Rtl} />

### Multi line states

The Dropdown component supports multiple options selection in two different state - single line and multiple lines.

<Canvas of={DropdownStories.MultiChoiceWithDifferentStates} />

### Async Options

The Dropdown component supports async loading of options.

<Canvas of={DropdownStories.AsyncDropdown} />

### Dropdown with avatar

<Canvas of={DropdownStories.DropdownWithAvatar} />

### Dropdown with icon

<Canvas of={DropdownStories.DropdownWithIcon} />

### Dropdown with chip colors

<Canvas of={DropdownStories.DropdownWithChipColors} />

### Dropdown with tooltips on items

<Canvas of={DropdownStories.DropdownWithTooltipsOnItems} />

## Do’s and Don’ts

<ComponentRules
  rules={[
    {
      positive: {
        component: (
          <Dropdown
            placeholder="Placeholder text here"
            options={[
              { value: 1, label: "Option 1" },
              { value: 2, label: "Option 2" },
              { value: 3, label: "Option 3" }
            ]}
            className="dropdown-stories-styles_rules-spacing"
          />
        ),
        description:
          "Use the dropdown as a closed component. Users should normally be allowed only to click on the items; search is not recommended, though possible."
      },
      negative: {
        component: (
          <Dropdown
            menuIsOpen
            placeholder="Placeholder text here"
            options={[
              { value: 1, label: "Option 1" },
              { value: 2, label: "Option 2" },
              { value: 3, label: "Option 3" }
            ]}
            className="dropdown-stories-styles_rules-spacing"
          />
        ),
        description: (
          <>
            Don't keep the dropdown component in open mode as permanent state. If this is a design requirement consider
            use <StorybookLink page="Inputs/Combobox">Combo box</StorybookLink> instead.
          </>
        )
      }
    }
  ]}
/>

## Use cases and examples

### Multiple dropdown with renderers as options

Inside the advanced filters, a user can select multiple people from the dropdown menu, and they will be shown as Chips.

<Canvas of={DropdownStories.DropdownWithChips} />

### Searchable Dropdown

In case of multiple options, you can use the `onInputChange` prop to allow filtering options.

<Canvas of={DropdownStories.SearchableDropdown} />

### Dropdown with labels

A dropdown menu can include labels.

<Canvas of={DropdownStories.DropdownWithLabels} />

### Dropdown with virtualized items

A dropdown with many items, can be virtualized using `isVirtualized`.

<Canvas of={DropdownStories.VirtualizedDropdown} />

### Dropdown inside a form

A classic dropdown presents options a user needs to choose from.

<Canvas of={DropdownStories.DropdownInsideAForm} />

### Dropdown with groups

Dropdown menu can be organized into groups. It can be either by group title or divider.

<Canvas of={DropdownStories.DropdownWithGroups} />

### Dropdown inside popover

Use <code>menuPosition={Dropdown.menuPositions.FIXED}</code> prop attribute for displaying dropdown inside popover (like our Modal
component) or container with overflow hidden content.

<TipDevTipPopover />

<Canvas of={DropdownStories.DropdownInsidePopover} />

### Dropdown with loading

If importing the dropdown options may take time, you can reflect this to the user using Dropdown isLoading flag with optional custom message.

<Canvas of={DropdownStories.DropdownWithLoading} />

### Dropdown with ref

If you need to programmatically control Dropdown state, use `ref` prop. Pay attention that type of returned ref will be `StateManager` from <Link withoutSpacing href="https://react-select.com/home">`react-select`</Link> library.

<Canvas of={DropdownStories.DropdownWithRef} />

### Dropdown value selection

Control the value selection mechanism with the <code>tabSelectsValue</code> (default: true) prop.

<Canvas of={DropdownStories.DropdownValueSelection} />

## Related components

<RelatedComponents componentsNames={[COMBOBOX, SPLIT_BUTTON, MENU]} />