## Feature Examples
### Size
- description: Adjust the component size using the size prop.
large emphasize fields in onboarding flows.medium is the default size used in most cases.small should be used in dense layouts.
);
};
```
### Border
- description: Style the component using the border prop which supports four styles:
For forms, use standard. When the component is used to filter, use round. For titles that can be edited on click, use bottomLine. In the Content Manager’s spreadsheet, use none.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
];
return (
);
};
```
### Status
- description: Use the status prop to control component status.
error highlights an invalid selection.warning highlights a value that can’t be validated or impacts a user’s business.loading shows that the value is loading.
Hide the status suffix and indicate the state with a border color by setting hideStatusSuffixto true.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
];
return (
);
};
```
### Status message
- description: Add text that explains the status or what action the user should take with the statusMessage prop.
Showing the status message inline, directly below the dropdown is preferred in all default cases.
To add an accessible inline message, wrap the component in a statusMessage. To add a status message in a tooltip that requires users to hover on the icon, use the statusMessage prop. Control tooltip placement with tooltipPlacement prop.
View more inline status message examples in
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
];
return (
For all default cases:
For narrow layouts only:
);
};
```
### Disabled
- description: Disable all input interactions with the disabled prop. Use it to highlight unavailable functions.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
];
return Add additional information to prefix and suffix props (e.g. text, icons, buttons) to support the dropdown value.
- example:
```jsx
() => {
const discountSuffixOptions = [
{ id: 0, value: '5' },
{ id: 1, value: '10' },
{ id: 2, value: '15' },
];
const discountAffixOptions = [
{ id: 0, value: '10' },
{ id: 1, value: '20' },
{ id: 2, value: '30' },
];
const languageOptions = [
{ id: 0, value: 'English' },
{ id: 1, value: 'French' },
{ id: 2, value: 'Spanish' },
];
const employeeOptions = [
{ id: 0, value: 'Employee 1' },
{ id: 1, value: 'Employee 2' },
{ id: 2, value: 'Employee 3' },
];
return (
%}
options={discountSuffixOptions}
/>
$}
options={discountAffixOptions}
/>
);
};
```
### Clear button
- description: Enable a button that clears the dropdown value by using the clearButton prop. Show it when the field value is optional or has to be cleared often.
- example:
```jsx
() => {
const [selectedOption, setSelectedOption] = React.useState(0);
const options = [
{ id: 0, value: 'Click clear button to remove selection' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
];
return (
setSelectedOption(null)}
onSelect={option => setSelectedOption(option.id)}
selectedId={selectedOption}
options={options}
/>
);
};
```
### Fixed header and footer
- description: Add related actions to fixedFooter or fixedHeader areas. These headers and footers keep their position on scroll.
- example:
```jsx
() => {
const options = [
{ id: 1, value: 'Option 1' },
{ id: 2, value: 'Option 2' },
{ id: 3, value: 'Option 3' },
{ id: 4, value: 'Option 4' },
{ id: 5, value: 'Option 5' },
{ id: 6, value: 'Option 6' },
{ id: 7, value: 'Option 7' },
{ id: 8, value: 'Option 8' },
{ id: 9, value: 'Option 9' },
];
return (
Use three props to build custom layouts:
listItemSectionBuilder groups items into sections by type. listItemActionBuilder adds a text button for related list actions. listItemSelectBuilder builds custom list designs.
);
};
```
### List container dimensions
- description: Control the container size for the list of options with these props:
maxHeightPixels specifies the maximum height for longer lists.dropdownWidth matches content width or specifies pixels. Set width to ‘auto’ or ‘max-content.’minWidthPixels manually increases dropdown popover width.
By default, the dropdown matches the input field width.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
{ id: 3, value: 'Option 4' },
{ id: 4, value: 'Option 5' },
{ id: 5, value: 'Option 6' },
{ id: 6, value: 'Option 7' },
{ id: 7, value: 'Option 8' },
];
return (
);
};
```
### Marked option
- description: Once the dropdown is opened, use the markedOption to highlight the option.
- example:
```jsx
Switch to native support for mobile usage. Avoid using it for desktop applications.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
{ id: 3, value: 'Option 4' },
];
return Control text overflow in the field with the textOverflow. Apply clip or ellipsis.
Dropdown list options wrap by default. To apply ellipsis, select the items to be displayed with the listItemSelectBuilder. This isn't recommended.
- example:
```jsx
() => {
const options = [
{ id: 0, value: 'Option 1' },
{ id: 1, value: 'Option 2' },
{ id: 2, value: 'Option 3' },
{ id: 3, value: 'Option 4' },
];
const longOptions = [
{
id: 0,
value: 'This is a long value that make dropdown layout grow',
},
{
id: 1,
value: 'This is a long value that make dropdown layout grow',
},
{
id: 2,
value: 'This is a long value that make dropdown layout grow',
},
];
const longOptionsWithEllipsis = [
listItemSelectBuilder({
id: 0,
title: 'This is a long value that make dropdown layout grow',
ellipsis: true,
}),
listItemSelectBuilder({
id: 0,
title: 'This is a long value that make dropdown layout grow',
ellipsis: true,
}),
listItemSelectBuilder({
id: 0,
title: 'This is a long value that make dropdown layout grow',
ellipsis: true,
}),
];
return (
);
};
```
## Developer Examples
### Lazy loading
- description: Gradually load items with infiniteScroll, loadMore and hasMore props.
- example:
```jsx
() => {
const [data, setData] = React.useState([]);
const fetchMoreData = () =>
Promise.resolve(
fetch(`/api/dropdown?limit=${5}&offset=${data.length}`),
).then(results => setData([...data, ...results]));
React.useEffect(() => {
fetchMoreData();
}, []);
return (
Component can be used in controlled mode by passing selectedId and onSelect props.
- example:
```jsx
() => {
const [selectedId, setSelected] = React.useState(0);
const options = [
listItemSelectBuilder({
id: 0,
prefix: (
),
title: 'Home address',
label: 'Home address',
}),
listItemSelectBuilder({
id: 1,
title: 'Work address',
label: 'Work address',
prefix: (
),
}),
listItemSelectBuilder({
id: 2,
title: 'Mailing address',
label: 'Mailing address',
prefix: (
),
}),
listItemSelectBuilder({
id: 3,
title: 'Shipping address',
label: 'Shipping address',
prefix: (
),
}),
listItemSelectBuilder({
id: 4,
title: 'Other',
label: 'Other',
prefix: (
),
}),
];
return (
option.label}
onSelect={(e) => setSelected(e.id)}
options={options}
/>
);
};
```
## Common Use Case Examples
### Settings panel
- description: Use dropdown to let users select a single item from a predefined list of options in a settings panel.
- example:
```jsx
() => {
const [selectedOption, setSelectedOption] = React.useState(0);
const [value, setValue] = React.useState(2);
const options = [
{ id: 0, value: 'Image' },
{ id: 1, value: 'Video' },
{ id: 2, value: 'Image and video' },
{ id: 3, value: 'Document' },
{ id: 4, value: 'Audio' },
];
return (
setSelectedOption(option.id)}
selectedId={selectedOption}
/>
Required
);
};
```
### Prefix icon
- description: Use listItemSelectBuilder to create custom layouts for options in the dropdown. For example, use avatars, icons or images as prefix icons.
- example:
```jsx
() => {
const options = [
listItemSelectBuilder({
id: 0,
prefix: (
),
title: 'Home address',
label: 'Home address',
}),
listItemSelectBuilder({
id: 1,
title: 'Work address',
label: 'Work address',
prefix: (
),
}),
listItemSelectBuilder({
id: 2,
title: 'Mailing address',
label: 'Mailing address',
prefix: (
),
}),
listItemSelectBuilder({
id: 3,
title: 'Shipping address',
label: 'Shipping address',
prefix: (
),
}),
listItemSelectBuilder({
id: 4,
title: 'Other',
label: 'Other',
prefix: (
),
}),
];
return (
option.label}
options={options}
/>
);
};
```
### Grouping
- description: Use listItemSectionBuilder within the drop down to group options into categories.
- example:
```jsx
|
|
;
```