Dropdown

Dropdowns are used to select between choices. Dropdown list items can have a variety of content, including text, avatars, icons, and brand logomarks.

Overview

Resources

Install


yarn add @activecampaign/camp-components-dropdown

Minimum required props

Property	Description	Type
`selected`	Currently selected option, controlled by the parent	object `{}`
`onSelect`	A function that takes one argument `changes` (single select) `option` (multiselect) that gets called when a selection is made	function
`options`	An array of options and/or option groups, if using option groups, each item in the array must have “label” and “children” values	array `[]`
`optionToString`	Used to format an option object to a string for accessibility use and default formatting, also used by the built-in search method	function

Recommended props

Property	Description	Type
`onSelectAll`	A function that takes one argument `changes` and is called whenever the user clicks the Select All checkbox for multiselect dropdown	function

Variations

Single select

Use the single select dropdown to allow users to pick a single option. The appearance prop may be set to inline, floating, or default for appearance variations. The labelPosition prop can put the label on the left or top with the default being top.

Inline


<Dropdown appearance="inline" label="Select an option" placeholder="Select" />

Floating


<Dropdown appearance="floating" label="Select an option" placeholder="Select" />

Label positioning

The labelPosition top accepts left or top (default is top) .


<Dropdown labelPosition="left" label="Select an option" placeholder="Select" />

Code example

The basic props in this code example will be required for any dropdown implementation. All the other examples will assume these props are being provided in some form.


import Dropdown from '@activecampaign/camp-components-dropdown';
 
const MyComponent = () => {
  const [selectedOption, setSelectedOption] = useState([]);
 
  const options = ['String 1', 'String 2', 'String 🔴', 'String 🔵', 'String 👵', 'String 👶'];
 
  const handleSelect = (option) => {
    const { selectedItem } = option;
    setSelectedOption(selectedItem);
  };
 
  return (
    <Dropdown
      options={options}
      // optionToString callback is required:
      optionToString={(option) => {
        // Safety check for null
        if (option === null) {
          return '';
        }
 
        // Return a simple string
        if (typeof option === 'string') {
          return option;
        }
 
        // if option is an object, returned desired property
        return option.value;
      }}
      onSelect={handleSelect}
      selected={selectedOption}
    />
  );
};

Configuring `options`

For the options prop, you may choose to use an array of strings or an array of objects. If you choose to use objects, the disabled (boolean) and render properties may be used to further customize each individual object.


// Options as strings
const options = ['apple', 'banana', 'orange'];
 
// Options as objects
const options = [
  {
    name: 'cat',
    type: 'feline',
    disabled: false,
    render: (option) => <div>{option.name}</div>,
  },
  {
    name: 'mouse',
    type: 'rodent',
    disabled: true,
    render: (option) => (
      <p>
        {option.name}, {option.type}
      </p>
    ),
  },
  {
    value: 'dog',
    type: 'canine',
    disabled: false,
    render: (option) => (
      <span>
        {option.name}: {option.type}
      </span>
    ),
  },
];

Configuring `optionToString`

The optionToString prop is used as the default string representation of an option as well as for accessibility (the screen reader needs to know how to read out an option even if it’s just an image, an avatar plus text, or anything else), therefore this prop is required. This will also be used as the default text that search terms are compared to, unless you control search yourself.


const myStringOptions = ['Option 1', 'Option 2', 'Option 3'];
 
<Dropdown options={myStringOptions} optionToString={(option) => option || ''} {...props} />;
 
const myObjectOptions = [
  {
    name: 'Fu',
    value: 1,
  },
  {
    name: 'Bar',
    value: 2,
  },
];
 
<Dropdown options={myObjectOptions} optionToString={(option) => option.name || ''} {...props} />;

Configuring `selectionOperator`

selectionOperator tells the dropdown how to determine if an option is the selected one; otherwise, direct comparison is used by default. In this example, the selected option will fail to be styled as selected in the options menu, since selected === option will never be true for any particular option.


const failingExample = () => {
  const options = [
    { name: 'Fu', value: 1 },
    { name: 'Bar', value: 2 },
  ];
  const [selected, setSelected] = useState();
 
  return (
    <Dropdown
      options={options}
      optionToString={(option) => option.name || ''}
      selected={selected}
      onSelect={(option) => setSelected(option.value)}
    />
  );
};

To fix the problem, we can simply inform the dropdown how to check if an option is active by providing an operator:


selectionOperator={(option, selected) => selected && option.value === selected.value}

Configuring `noOptionsMessage`

Provide a string to this prop to inform the user that no options are visible, either because there are none for some reason, or maybe because they are loading asynchronously. Note that there’s another prop for when search is enabled and a query returns no results (noSearchResultsMessage).


<Dropdown noOptionsMessage="No options to show..." {...props} />

Custom styling options

There are three methods to style options.

By default, the optionToString result is rendered.
The defaultOptionRenderer prop allows you to provide a render function that’s applied to all options.
Providing a render method to an option allows you to determine how that individual option is rendered. This method overrides all others.


const myExample = () => {
  const options = [
    {
      text: 'Option 1',
    },
    {
      text: 'Option 2',
      // This render method will be used for this option
      render: (option) => (
        <Styled styles={{ display: 'flex', alignItems: 'center' }}>
          <Icon use="pencilEdit" mr="sp300" />
          <span>{option.text}</span>
        </Styled>
      ),
    },
  ];
  return (
    <Dropdown
      options={options}
      defaultOptionRenderer={(option) => (
        // Option 1 will be rendered with this style,
        // as will any other options that don't provide their own render function.
        <Styled styles={{ display: 'flex', alignItems: 'center' }}>
          <Avatar size="small" mr="sp300" />
          <span>{option.text}</span>
        </Styled>
      )}
      // No options will be rendered with this string in this case,
      // but it's still required for screen readers.
      optionToString={(option) => option.text || ''}
      {...props}
    />
  );
};

Option groups

Basic options groups are automatically rendered if an option contains label and children values. You can mix options and option groups.


// Will render an option, then a group header with two options, then another option.
const groupedOptions = [
  { text: 'Option 1' },
  {
    label: 'Group 1',
    children: [{ text: 'Option A' }, { text: 'Option B' }],
  },
  { text: 'Option 2' },
];

`helperText` as information or error messaging

The helperText prop allows you to pass a string in to be rendered below the input. This text is styled with a subdued slate color as information text or becomes red when invalid is set to true.


// Rendered as subdued text below the input
<Dropdown
  helperText="Here's some text to help you fill this form properly"
  {...props}
/>
 
// Rendered as strawberry error text below the input
<Dropdown
  helperText="This field is required."
  invalid
  {...props}
/>

Search

The dropdown component will control search by default and compare with the string produced with the optionToString function. Search is controlled by the dropdown component by default, but you can also choose to control search yourself for use cases like integrating API requests, which change the options in your dropdown list.

Enable search by setting isSearchable to true. When enabling search, you’ll want to provide a selectionOperator so that the actively selected item remains visually selected in the options menu when search queries are entered since the filtered results are not a direct reference to the original options array.

Two additional props become required when search is enabled:

searchPlaceholder for providing search input placeholder text.
noSearchResultsMessage for providing a message when no results match the search query.


<Dropdown
  isSearchable
  searchPlaceholder="Search"
  noSearchResultsMessage="No options match"
  label="Select an option"
  placeholder="Select"
/>}

The dropdown menu enables optionally rendering “actions” at the bottom of the menu using the renderMenuActions callback. In the example below, we’re simply returning the JSX we want rendered at the bottom of the menu.


<Dropdown
  renderMenuActions={(props) => {
    const onClick = () => {
      console.log('Button clicked');
      console.log('Available props: ', props);
      props & props.closeMenu();
    };
 
    return (
      <Styled styles={{ display: 'flex' }}>
        <Button.Fill onClick={onClick} mr="sp200" styles={{ width: '100%' }}>
          Primary Action
        </Button.Fill>
        <Button.Outline onClick={onClick} ml="sp200" styles={{ width: '100%' }}>
          Secondary Action
        </Button.Outline>
      </Styled>
    );
  }}
  placeholder="Select"
  label="Select an option"
/>

Custom trigger content

It is possible to replace the default content that shows within the dropdown field when an item is selected with custom trigger content. This can be particularly useful for multiselect, where many items are selected, and with single select when a selection is particularly long.

Configure custom trigger content by using the prop setCustomTriggerContent. Pass a function which accepts one argument selected which is the currently selected options. The function may return a string or JSX to render in the trigger. If the function returns null or undefined, the default option string will be used in the trigger in that case. In this example, there is a custom string configured for the case where the user selects String 2.


// in this example, return a specific trigger string for one particular selected option
const setCustomTriggerContent = (selected) => {
  if (selected === 'String 2') {
    return 'String 2 has been selected';
  }
};
 
return <Dropdown {...props} setCustomTriggerContent={setCustomTriggerContent} />;

Multiselect

Use the multi select dropdown to allow users to pick and search from multiple options from a list.

Code example

The basic props in this code example will be required for any dropdown implementation. All the other examples will assume these props are being provided in some form.


import { DropdownMultiselect } from '@activecampaign/camp-components-dropdown';
 
const MyDropdown = (props) => {
  const [selected, setSelected] = useState([]);
 
  const handleSelect = (changes) => {
    const { selectedItem } = changes;
 
    // Safety check
    if (!selectedItem) return;
 
    // Check for array
    const hasSelectedArray = !!selected && selected.length > 0;
 
    // Get index of currently selected option
    const index = hasSelectedArray
      ? selected.findIndex((x) => {
          // Simple compare for strings
          if (typeof selectedItem === 'string' || typeof x === 'string') {
            return selectedItem === x;
          }
 
          // Check value key, for other option examples
          return selectedItem.value == x.value;
        })
      : -1;
 
    // Copy the selected array
    const selectedArray = hasSelectedArray ? Array.from(selected) : [];
 
    // If the item is already selected, remove it from the list
    if (index > 0) {
      setSelected([...selectedArray.slice(0, index), ...selectedArray.slice(index + 1)]);
    }
    // If removing the last selected item
    else if (index === 0) {
      setSelected([...selectedArray.slice(1)]);
    }
    // If the item is not already selected, add it to the list
    else {
      setSelected([...selectedArray, selectedItem]);
    }
  }
 
  const handleSelectAll = (options) => {
    setSelected(options);
  }
 
  const selectionOperator = (optionParam: Option, selectedParam: selectedMulti) => {
    // Only included here for type help
    if (typeof optionParam === 'string') {
      return false;
    }
 
    // Safety Check
    if (selectedParam === null || selectedParam === undefined) {
      return false;
    }
 
    // Check Equality
    return selectedParam.some((selectedOption) => {
      // Theres is an edge here;
      if (typeof selectedOption === 'string') {
        // If you had OptionGroups w/ strings, you would need to adjust this
        return false;
      }
      // All of our option examples use a `value` key to test equality
      return selectedOption.value === optionParam.value;
    });
  };
 
  const optionToStringDefault = (option: Option | null) => {
    // Safety check for null
    if (option === null) {
      return '';
    }
    // Return a simple string
    if (typeof option === 'string') {
      return option;
    }
 
    // Return the desired value from your options object
    return option.value;
  };
 
  return (
    <DropdownMultiselect
      label='Select an option'
      options={[
        {
          value: 'Option 1'
        },
        {
          value: 'Option 2'
        },
        {
          value: 'Option 3'
        },
        {
          value: 'Option 4'
        },
        {
          value: 'Option 5'
        }
      ]}
      optionToString={optionToStringDefault}
      selected={selected}
      onSelect={handleSelect}
      selectionOperator={selectionOperator}
      onSelectAll={handleSelectAll}
    />
  );
}

Configuring `setCustomTriggerContent`

Configure custom trigger content by using the prop setCustomTriggerContent. Pass a function which accepts one argument selected which is the currently selected options. The function may return a string or JSX to render in the trigger. If the function returns null or undefined, the default option string will be used in the trigger in that case. In this example, there is a custom string configured for the case where the user selects all options in the list.


const options = [
  {
    value: 'Option 1',
  },
  {
    value: 'Option 2',
  },
  {
    value: 'Option 3',
  },
  {
    value: 'Option 4',
  },
  {
    value: 'Option 5',
  },
];
 
// in this example, set a custom string when all options are selected
const setCustomTriggerContent = (selected) => {
  // type check
  if (!Array.isArray(selected)) return null;
  // get length of total options and compare with length of selected
  if (options.length === selected.length) {
    return 'All options selected';
  }
};
 
return (
  <DropdownMultiselect
    {...props}
    options={options}
    setCustomTriggerContent={setCustomTriggerContent}
  />
);

In this example, there is a custom Chip element that will render for the case where the user selects all options in the list.


import Chip from '@activecampaign/camp-components-chip';
 
const myDropdown = () => {
  const options = [
    {
      value: 'Option 1',
    },
    {
      value: 'Option 2',
    },
    {
      value: 'Option 3',
    },
    {
      value: 'Option 4',
    },
    {
      value: 'Option 5',
    },
  ];
 
  // in this example, set a custom string when all options are selected
  const setCustomTriggerElementMulti = (selected) => {
    // type check
    if (!Array.isArray(selected)) return null;
    // get length of total options and compare with length of selected
    if (options.length === selected.length) {
      return <Chip appearance="mint" text="All options selected" type="fill" />;
    }
  };
 
  return (
    <DropdownMultiselect
      {...props}
      options={options}
      setCustomTriggerContent={setCustomTriggerContent}
    />
  );
};

Indeterminate option

You can also mark a multiselect option as indeterminate, which is helpful when that option may or may not apply in a given circumstance (e.g., when selecting multiple campaigns to add/remove a label to and only some of them have the label).


<DropdownMultiselect
  ...
  options={[
    { value: 'Option 1' },
    { value: 'Option 2' },
    { value: 'Option 3', indeterminate: true },
    { value: 'Option 4' },
    { value: 'Option 5', indeterminate: true },
  ]}
/>

Migration guide

Migrating from 1.x to 2.x

Prop changes

Updated props

Prop	Details
`onSelect`	Type change: `(changes: UseSelectStateChange<selectedSingle>) => void` More information below on implementation for 2.x

Deprecated props

Prop	Details
`multiselect`	See below for more information on the multiselect implementation for 2.x
`showTriggerArrow`	The trigger arrow will always appear when using the standard dropdown trigger. If you need a trigger without the arrow or with other major style changes, use the `renderTrigger` prop to render a custom trigger that will replace the standard trigger.
`menuActions`	To render menu actions, use the new `renderMenuActions` prop.
`selectAll`	The select all label is a translated string configured by Dropdown and cannot be modified with props.
`useAccordionGroups`	The 2.x version of dropdown does not support collapsing groups.
`popoverTestId`	All test ID props that were deprecated have been restored. Note that `popoverTestId` has not yet been restored.

The multiselect prop is deprecated. The new way to implement a multiselect dropdown is to import the named component DropdownMultiselect and implement this component instead of the original Dropdown component.
See code example

onSelect

The onSelect function should take one argument changes which will need to be destructured to access the value of selectedItem.


// Compare to the previous implementation (DO NOT USE)
const previousHandleSelect = (option) => {
  // your selection handler here, referencing the option as the selected item
};
 
// New implementation in version 2 (NEW! Use this!)
const newHandleSelect = (changes) => {
  const { selectedItem } = changes;
  // your selection handler here, referencing selectedItem as the selected item
};
 
render(<Dropdown onSelect={newHandleSelect} {...props} />);

Usage

Best practices

Dropdown menus work best for small data sets where a user has anywhere from 5 to 15 items to choose from. For smaller datasets, checkboxes or radios should be used (depending on single or multiselect), and for datasets larger than 15, it is recommended to use a combobox instead.
When grouped, liste items should be in some logical order that makes it easy for the user to read and understand, whether that is numerical or alphabetical or some other contextually-based grouping.

Accessibility

Keyboard support

Tab or (shift + tab to move backward) opens and closes the dropdown and moves focus. If the dropdown is closed the only item in tab index should be DropdownTrigger, then tab will navigate to the next available tab indexed item in the page. If the dropdown is open, the tab order of the items within the DropdownMenu is as follows, if these items are included in the menu: search, select all/none, menu actions.
To open the dropdown on focus, press space to open the menu. When the dropdown menu is open, use ↑ or ↓ to navigate list items and enter to select or deselect an item within the list. When selecting items, the menu closes after selecting in a single select dropdown but remains open in a multiselect dropdown.
↑ or ↓ can also be used to open a closed dropdown menu.
If a multiselect dropdown has a search, upon open of the dropdown, the search input is in focus. Search can either be navigated away from using tab or arrow keys.
esc will close the dropdown when focused anywhere inside the component.

Similar components

Radio Button

Allows the user to select one option from a set.

Checkbox

Allows users to select one or more items from a set.

Combobox

A combination of a text input field and a dropdown list.

Dropdown

Overview

Resources

Install

Minimum required props

Recommended props

Variations

Single select

Inline

Floating

Label positioning

Code example

Configuring options

Configuring optionToString

Configuring selectionOperator

Configuring noOptionsMessage

Custom styling options

Option groups

helperText as information or error messaging

Search

Menu actions

Custom trigger content

Multiselect

Code example

Configuring setCustomTriggerContent

Indeterminate option

Migration guide

Migrating from 1.x to 2.x

Prop changes

Updated props

Deprecated props

Multiselect Dropdown

onSelect

Usage

Best practices

Accessibility

Keyboard support

Similar components

Radio Button

Checkbox

Combobox

Configuring `options`

Configuring `optionToString`

Configuring `selectionOperator`

Configuring `noOptionsMessage`

`helperText` as information or error messaging

Configuring `setCustomTriggerContent`