Take a look at our Storybook for more information about this component.
Check the Lexicon Dropdown Pattern for a more in-depth look at the motivations and proper usage of this component.
WarningBefore you get started with this doc, read about Clay's fundamentals of composition to move on. The information below is assuming you have read about Clay's compositional philosophy and learned about the terms.
DropDown's composition gives you the space to create more complex DropDowns, such as adding a form within DropDown, and creating simple DropDowns with the high-level ClayDropDownWithItems component that covers most basic Lexicon use cases.
Composing
You may want to use only the content of DropDown for other cases, such as mounting an Autocomplete, so use DropDown.Menu instead of DropDown which gives you the flexibility to only control content without a trigger.
DropDown consists of a DropDown.Menu that controls the trigger and uses it as the basis for aligning DropDown content.Using dropdown without a trigger
You may want to create a trigger that is not necessarily in the same tree as DropDown, due to HTML markup issues, for these cases you can use <ClayDropDown.Menu />.
Using <ClayDropDown.Menu /> allows you to better control the state of DropDown but you will have to deal with visibility, focus management, and other details.
import ClayDropDown from '@clayui/drop-down';
import React, {useState, useRef} from 'react';
const Menu = ({children, hasLeftSymbols, hasRightSymbols}) => {
const triggerElementRef = useRef(null);
const [expand, setExpand] = useState(false);
const menuElementRef = useRef(null);
const handleExpand = event => {
// This is not ideal for allowing you to have more than
// one trigger for the same content but it simulates the
// advantages of controlling `DropDown.Menu`.
triggerElementRef.current = event.target;
setExpand(!expand);
};
return (
<div>
<div>
<button type="button" onClick={handleExpand}>
Home
</button>
</div>
<div>
<button type="button" onClick={handleExpand}>
Product
</button>
</div>
<ClayDropDown.Menu
active={expand}
alignElementRef={triggerElementRef}
hasLeftSymbols={hasLeftSymbols}
hasRightSymbols={hasRightSymbols}
onSetActive={() => setExpand(!expand)}
ref={menuElementRef}
>
{children}
</ClayDropDown.Menu>
</div>
);
};DropDownWithItems
Allows you to create a simple DropDown, through its API you are able to create a Menu with groups of checkboxes and radios, links, buttons, search, caption, etc.
API
ClayDropDown
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
active | boolean | false | Flag to indicate if the DropDown menu is active or not. | |
alignmentPosition | number | Default position of menu element. Values come from `./Menu`. | ||
containerElement | React.JSXElementConstructor<any> | 'div' | 'li' | 'div' | HTML element tag that the container should render. | |
hasRightSymbols | boolean | Flag to indicate if menu contains icon symbols on the right side. | ||
hasLeftSymbols | boolean | Flag to indicate if menu contains icon symbols on the left side. | ||
menuElementAttrs | React.HTMLAttributes<HTMLDivElement> | Prop to pass DOM element attributes to <DropDown.Menu />. | ||
onActiveChange | (val: boolean) => void | true | Callback for when the active state changes. | |
trigger | React.ReactElement & { ref?: (node: HTMLButtonElement | null) => void; } | true | Element that is used as the trigger which will activate the dropdown on click. |
ClayDropDown.Action
Extends from React.HTMLAttributes<HTMLButtonElement>ClayDropDown.Caption
Extends from React.HTMLAttributes<HTMLDivElement>ClayDropDown.Divider
Extends from React.HTMLAttributes<HTMLLIElement>ClayDropDown.Group
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
header | string | Value provided is a display component that is a header for the items in the group. |
ClayDropDown.Help
Extends from React.HTMLAttributes<HTMLDivElement>ClayDropDown.Item
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
active | boolean | Flag that indicates if item is selected. | ||
disabled | boolean | Flag that indicates if item is disabled or not. | ||
href | string | Path for item to link to. | ||
innerRef | React.Ref<any> | |||
spritemap | string | Path to icon spritemap from clay-css. | ||
symbolLeft | string | Flag that indicates if there is an icon symbol on the left side. | ||
symbolRight | string | Flag that indicates if there is an icon symbol on the right side. |
ClayDropDown.ItemList
Extends from React.HTMLAttributes<HTMLUListElement>ClayDropDown.Menu
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
active | boolean | Flag to indicate if menu is showing or not. | ||
alignElementRef | React.RefObject<HTMLElement> | true | HTML element that the menu should be aligned to | |
autoBestAlign | boolean | true | Flag to suggest or not the best region to align menu element. | |
alignmentPosition | number | TPointOptions | Align.BottomLeft | Default position of menu element. Values come from above. Align.TopCenter = 0; Align.TopRight = 1; Align.RightCenter = 2; Align.BottomRight = 3; Align.BottomCenter = 4; Align.BottomLeft = 5; Align.LeftCenter = 6; Align.TopLeft = 7; Defaults to BottomLeft You can also pass an array of strings, corresponding to the points of the targetNode and sourceNode, `[sourceNode, targetNode]`. Points can be 't'(top), 'b'(bottom), 'c'(center), 'l'(left), 'r'(right). For example: `['tl', 'bl']` corresponds to the bottom left alignment. | |
hasLeftSymbols | boolean | Flag to indicate if menu is displaying a clay-icon on the left. | ||
hasRightSymbols | boolean | Flag to indicate if menu is displaying a clay-icon on the right. | ||
onSetActive | (val: boolean) => void | true | Callback function for when active state changes. |
ClayDropDown.Search
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
onChange | (event: React.ChangeEvent<HTMLInputElement>) => void | true | Callback for when input value changes. | |
spritemap | string | Path to the location of the spritemap resource. | ||
value | React.ReactText | true | Value of the searchInput |
ClayDropDownWithItems
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
spritemap | string | The path to the SVG spritemap file containing the icons. | ||
items | Array<IItem> | true | List of items to display in drop down menu | |
alignmentPosition | number | Default position of menu element. Values come from `./Menu`. | ||
caption | string | Informational text that appears at the end or above the `footerContent` prop. | ||
className | string | |||
containerElement | React.ComponentProps< typeof ClayDropDown >['containerElement'] | HTML element tag that the container should render. | ||
footerContent | React.ReactElement | Add an action button or any other element you want to be fixed position to the footer from the DropDown. | ||
trigger | React.ReactElement | true | Element that is used as the trigger which will activate the dropdown on click. | |
helpText | string | Add informational text at the top of DropDown. | ||
menuElementAttrs | React.ComponentProps< typeof ClayDropDown >['menuElementAttrs'] | Prop to pass DOM element attributes to <DropDown.Menu />. | ||
onSearchValueChange | (newValue: string) => void | () => {} | Callback will always be called when the user is interacting with search. | |
searchable | boolean | Flag to show search at the top of the DropDown. | ||
searchProps | React.ComponentProps<typeof Search> | Pass the props to ClayInput. | ||
searchValue | string | '' | The value that will be passed to the search input element. |