@zendeskgarden/react-dropdowns

What is @zendeskgarden/react-dropdowns?

@zendeskgarden/react-dropdowns is a React component library that provides a set of accessible and customizable dropdown components. These components are designed to be used in building user interfaces that require dropdown functionality, such as select menus, autocomplete inputs, and more.

What are @zendeskgarden/react-dropdowns's main functionalities?

Select Dropdown

The Select Dropdown feature allows users to choose from a list of options. The code sample demonstrates how to create a dropdown with three options using the Dropdown, Select, and Item components.

import { Dropdown, Select, Item } from '@zendeskgarden/react-dropdowns';

const Example = () => (
  <Dropdown>
    <Select>
      Select an option
    </Select>
    <Item value="option-1">Option 1</Item>
    <Item value="option-2">Option 2</Item>
    <Item value="option-3">Option 3</Item>
  </Dropdown>
);

Autocomplete Input

The Autocomplete Input feature provides a text input that suggests options as the user types. The code sample shows how to implement an autocomplete input with three fruit options.

import { Dropdown, Autocomplete, Item } from '@zendeskgarden/react-dropdowns';

const Example = () => (
  <Dropdown>
    <Autocomplete placeholder="Type to search...">
      <Item value="apple">Apple</Item>
      <Item value="banana">Banana</Item>
      <Item value="orange">Orange</Item>
    </Autocomplete>
  </Dropdown>
);

Multiselect Dropdown

The Multiselect Dropdown feature allows users to select multiple options from a list. The code sample illustrates how to create a multiselect dropdown with three options.

import { Dropdown, Multiselect, Item } from '@zendeskgarden/react-dropdowns';

const Example = () => (
  <Dropdown>
    <Multiselect placeholder="Select options">
      <Item value="option-1">Option 1</Item>
      <Item value="option-2">Option 2</Item>
      <Item value="option-3">Option 3</Item>
    </Multiselect>
  </Dropdown>
);

Other packages similar to @zendeskgarden/react-dropdowns

react-select

react-select is a flexible and customizable library for building dropdowns and select inputs in React. It offers a wide range of features including single and multi-select, async options, and customizable styles. Compared to @zendeskgarden/react-dropdowns, react-select provides more advanced customization options and is widely used in the React community.

downshift

downshift is a library that provides primitives to build flexible and accessible dropdown components. It focuses on providing the necessary building blocks for creating custom dropdowns, rather than pre-styled components. Compared to @zendeskgarden/react-dropdowns, downshift offers more control over the dropdown behavior and is ideal for developers who need to implement highly customized dropdowns.

react-autosuggest

react-autosuggest is a library for building autocomplete inputs in React. It provides a simple API for creating inputs that suggest options as the user types. Compared to @zendeskgarden/react-dropdowns, react-autosuggest is specifically focused on autocomplete functionality and offers more features related to suggestion handling and customization.

README

@zendeskgarden/react-dropdowns

This package includes components related to dropdowns in the Garden Design System.

Installation

npm install @zendeskgarden/react-dropdowns

# Peer Dependencies - Also Required
npm install react react-dom styled-components @zendeskgarden/react-theming

Usage

Combobox

import { ThemeProvider } from '@zendeskgarden/react-theming';
import { Field, Label, Combobox, Option } from '@zendeskgarden/react-dropdowns';

/**
 * Place a `ThemeProvider` at the root of your React application
 */
<ThemeProvider>
  <Field>
    <Field.Label>Label</Field.Label>
    <Combobox>
      <Option value="One" />
      <Option value="Two" />
      <Option value="Three" />
    </Combobox>
  </Field>
</ThemeProvider>;

Beyond this basic example, Garden's Combobox offers a comprehensive set of WAI-ARIA compliant combobox features. Key capabilities include:

• Controllable: The Combobox functions in both uncontrolled and controlled modes. Controlled mode enables aspects, such as input value, selection value(s), listbox expansion, and current option active index, to share and adapt to the surrounding UI.
• Autocomplete-able: Denotes the Combobox with list autocomplete. Filtering implementation is left to the API consumer.
• Selectable: The Combobox API ensures the selection of one or more listbox option values, while also supporting the W3C no autocomplete example for use cases like search.
• Multi-selectable: This feature enables the Combobox to provide WAI-ARIA multi-select listbox functionality with option-as-tag value rendering.
• Non-editable: The Combobox supports select-only mode, where the user cannot modify the <input>.
• Filterable: The Combobox offers various filtering methods for listbox options. Details of the filtering implementation are left to the API consumer.
• Markup-able: The Combobox can convert input value text to rich HTML markup on blur in single-selection mode.
• Decorate-able: The Combobox allows adding start and end media (SVG icons). Certain features will replace end media with Garden's standard dropdown chevron treatment.
• Group-able: The Combobox API utilizes fully accessible <OptGroup> components for grouping, similar to the corresponding HTML element.
• Compactible: Like other form elements, the Combobox supports compact sizing.
• Field-able: The Combobox builds on Garden’s Field API context to establish accessible relationships with corresponding Label, Hint, and Message components.
• Validate-able: The Combobox provides validation styling and accessibility comparable to other Garden form components.
• RTL theme-able: Functionality displays and operates correctly for left-to-right and right-to-left layouts.

Menu

import { ThemeProvider } from '@zendeskgarden/react-theming';
import { Menu, Item } from '@zendeskgarden/react-dropdowns';

/**
 * Place a `ThemeProvider` at the root of your React application
 */
<ThemeProvider>
  <Menu button="Choose an item">
    <Item value="item-01" label="One" />
    <Item value="item-02" label="Two" />
    <Item value="item-03" label="Three" />
  </Menu>
</ThemeProvider>;

Visit storybook for live examples.

Changelog

v9.2.0 (2024-11-21)

:rocket: New Feature

• dropdowns
  • #1971 feat(dropdowns): add hasSelection prop for use with <Option type="next"> (@jzempel)

:bug: Bug Fix

• tags, theming, typography
  • #1979 fix(theming): getColor shade default depends on transparency (@jzempel)

:seedling: Internal

• Other
  • #1977 chore(deps): bump serve-static, express and @zendeskgarden/scripts (@dependabot[bot])
  • #1976 chore(deps): bump send, express and @zendeskgarden/scripts (@dependabot[bot])
  • #1975 chore(deps): bump body-parser, express and @zendeskgarden/scripts (@dependabot[bot])
  • #1974 chore(deps): bump cookie, express and @zendeskgarden/scripts (@dependabot[bot])
• tables
  • #1972 chore(config): migrate renovate config (@renovate[bot])