Dropdown Menu

A dropdown menu displays a list of options for the element that triggers it.

install	yarn add @clayui/drop-down
version	3.124.0

Stable 3.124.0 View in Lexicon CHANGELOG

DropDown
DropDown.Action
DropDown.Caption
DropDown.Divider
DropDown.Group
DropDown.Help
DropDown.Item
DropDown.ItemList
DropDown.Menu
DropDown.Search
DropDown.Section
DropDownWithItems
DropDownWithDrilldown

Property	Description
`active` `boolean`	Flag to indicate if the DropDown menu is active or not (controlled). This API is generally used in conjunction with `closeOnClickOutside=true` since often we are controlling the active state by clicking another element within the document.
`alignmentByViewport` `React.ComponentProps< typeof Menu >['alignmentByViewport']`	Flag to align the DropDown menu within the viewport.
`alignmentPosition` `React.ComponentProps<typeof Menu>['alignmentPosition']`	Default position of menu element. Values come from `./Menu`.
`containerElement` `React.JSXElementConstructor<any> \| 'div' \| 'li'`	HTML element tag that the container should render. The default value is 'div'
`closeOnClick` `boolean`	Flag that indicates whether to close DropDown when clicking on the item. The default value is false
`closeOnClickOutside` `React.ComponentProps< typeof Menu >['closeOnClickOutside']`
`defaultActive` `boolean`	Property to set the default value of `active` (uncontrolled). The default value is false
`filterKey` `string`	Defines the name of the property key that is used in the items filter test (Dynamic content).
`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> & Pick<React.ComponentProps<typeof Menu>, 'containerProps'>`	Prop to pass DOM element attributes to .
`menuHeight` `React.ComponentProps<typeof Menu>['height']`
`menuWidth` `React.ComponentProps<typeof Menu>['width']`
`onActiveChange` `InternalDispatch<boolean>`	Callback for when the active state changes (controlled). This API is generally used in conjunction with `closeOnClickOutside=true` since often we are controlling the active state by clicking another element within the document.
`offsetFn` `React.ComponentProps<typeof Menu>['offsetFn']`	Function for setting the offset of the menu from the trigger.
`renderMenuOnClick` `boolean`	Flag indicating if the menu should be rendered lazily The default value is false
`triggerIcon` `string \| null`	Flag indicating if the caret icon should be displayed on the right side. The default value is null
`trigger` `React.ReactElement & { ref?: (node: HTMLButtonElement \| null) => void; }`	Element that is used as the trigger which will activate the dropdown on click.
`role`	The default value is 'menu'

Extends from React.HTMLAttributes<HTMLButtonElement>Extends from React.HTMLAttributes<HTMLDivElement>Extends from React.HTMLAttributes<HTMLLIElement>

Property	Description
`header` `string`	Value provided is a display component that is a header for the items in the group.
`role` `string`	ARIA to define semantic meaning to content. The default value is 'group'

Extends from React.HTMLAttributes<HTMLDivElement>

Property	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>`
`roleItem` `string`	Sets the role accessibility property of the item. Set the item's container ( ) role use the role="" prop instead of roleItem="". The default value is 'menuitem'
`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.
`role`	The default value is 'presentation'

Extends from React.HTMLAttributes<HTMLUListElement>

Property	Description
`active` `boolean`	Flag to indicate if menu is showing or not. The default value is false
`alignElementRef` `React.RefObject<HTMLElement>`	HTML element that the menu should be aligned to
`alignmentByViewport` `boolean`	Flag to align the DropDown menu within the viewport. The default value is false
`autoBestAlign` `boolean`	Flag to suggest or not the best region to align menu element. The default value is true
`alignmentPosition` `number \| AlignPoints`	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. The default value is 5
`closeOnClickOutside` `boolean`	Flag to indicate if clicking outside of the menu should automatically close it. The default value is true
`containerProps` `IPortalBaseProps`	Props to add to the outer most container. The default value is {}
`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.
`height` `literal`	Adds utility class name `dropdown-menu-height-${height}`
`lock` `boolean`	Flag to lock focus within the scope. The default value is false
`focusRefOnEsc`Deprecated `React.RefObject<HTMLElement>`	Element ref to call focus() on after menu is closed via Escape key @deprecated since v3.80.0 - use `triggerRef` instead.
`offsetFn` `(points: AlignPoints) => [number, number]`	Function for setting the offset of the menu from the trigger.
`onActiveChange` `(value: boolean) => void`	Callback function for when active state changes.
`onSetActive`Deprecated `(value: boolean) => void`	Callback function for when active state changes. @deprecated since v3.52.0 - use `onActiveChange` instead.
`suppress` `Array<React.RefObject<HTMLElement>>`	Defines the reference of the elements that must be suppressed by the screen reader when the menu is opened.
`triggerRef` `React.RefObject<HTMLElement>`	Reference of the element that triggers the Menu.
`width` `'sm' \| 'shrink' \| 'full'`	The modifier class `dropdown-menu-width-${width}` makes the menu expand the full width of the page. - sm makes the menu 500px wide. - shrink makes the menu auto-adjust to text and max 240px wide. - full makes the menu 100% wide.
`role`	The default value is 'presentation'

Property	Description
`defaultValue` `string`	Initial value of the input (uncontrolled). The default value is ''
`formProps` `React.HTMLAttributes<HTMLFormElement>`	Props to add to form element The default value is {}
`onChange` `InternalDispatch<string>`	Callback for when input value changes (controlled).
`spritemap` `string`	Path to the location of the spritemap resource.
`submitProps` `React.HTMLAttributes<HTMLButtonElement>`	Props to add to the button component. The default value is { 'aria-label': 'Search', type: 'button', }
`value` `string`	Current value of the input (controlled).

Extends from React.HTMLAttributes<HTMLLIElement>

DropDownWithItems

Property	Description
`active` `boolean`	Flag to indicate if the DropDown menu is active or not (controlled).
`alignmentByViewport` `React.ComponentProps< typeof ClayDropDownMenu >['alignmentByViewport']`	Flag to align the DropDown menu within the viewport.
`alignmentPosition` `React.ComponentProps< typeof ClayDropDownMenu >['alignmentPosition']`	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`
`closeOnClickOutside` `React.ComponentProps< typeof ClayDropDown >['closeOnClickOutside']`
`containerElement` `React.ComponentProps< typeof ClayDropDown >['containerElement']`	HTML element tag that the container should render.
`defaultActive` `boolean`	Property to set the initial value of `active` (uncontrolled). The default value is false
`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 & { ref?: (node: HTMLButtonElement \| null) => void; }`	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 .
`menuHeight` `React.ComponentProps<typeof ClayDropDown>['menuHeight']`
`menuWidth` `React.ComponentProps<typeof ClayDropDown>['menuWidth']`
`messages` `string`	Prop to use language keys.
`offsetFn` `React.ComponentProps<typeof ClayDropDown>['offsetFn']`	Function for setting the offset of the menu from the trigger.
`onActiveChange` `InternalDispatch<boolean>`	Callback for when the active state changes (controlled).
`onSearchValueChange` `(newValue: string) => void`	Callback will always be called when the user is interacting with search. The default value is () => {}
`renderMenuOnClick` `React.ComponentProps< typeof ClayDropDown >['renderMenuOnClick']`	Flag indicating if the menu should be rendered lazily
`searchable` `boolean`	Flag to show search at the top of the DropDown.
`searchProps` `Omit< React.ComponentProps<typeof Search>, 'onChange' \| 'spritemap' \| 'value' >`	Pass the props to the Search component.
`searchValue` `string`	The value that will be passed to the search input element. The default value is ''
`triggerIcon` `string \| null`	Flag indicating if the caret icon should be displayed on the right side. The default value is null

DropDownWithDrilldown

Property	Description
`active` `boolean`	Flag to indicate if the menu should be initially open (controlled).
`alignmentByViewport` `React.ComponentProps< typeof ClayDropDownMenu >['alignmentByViewport']`	Flag to align the DropDown menu within the viewport.
`alignmentPosition` `React.ComponentProps< typeof ClayDropDownMenu >['alignmentPosition']`	Default position of menu element. Values come from `./Menu`.
`containerElement` `React.ComponentProps< typeof ClayDropDown >['containerElement']`	HTML element tag that the container should render.
`defaultActive` `boolean`	Property to set the initial value of `active` (uncontrolled). The default value is false
`defaultActiveMenu` `string`	The unique identifier of the menu that should be active on mount.
`initialActiveMenu`Deprecated `string`	The unique identifier of the menu that should be active on mount. @deprecated since v3.51.0 - use `defaultActiveMenu` instead.
`menuElementAttrs` `React.ComponentProps< typeof ClayDropDown >['menuElementAttrs']`	Prop to pass DOM element attributes to .
`menuHeight` `React.ComponentProps<typeof ClayDropDown>['menuHeight']`
`menuWidth` `React.ComponentProps<typeof ClayDropDown>['menuWidth']`
`messages` `Messages`	Messages for drilldown. The default value is { back: '', goTo: '', }
`menus` `{ [id: string]: React.ComponentProps<typeof Drilldown.Menu>['items']; }`	Map of menus and items to be used in the drilldown. Each key should be a unique identifier for the menu.
`offsetFn` `React.ComponentProps<typeof ClayDropDown>['offsetFn']`	Function for setting the offset of the menu from the trigger.
`onActiveChange` `InternalDispatch<boolean>`	Callback the will be invoked when the active prop is changed (controlled).
`spritemap` `string`	Path to spritemap
`renderMenuOnClick` `React.ComponentProps< typeof ClayDropDown >['renderMenuOnClick']`	Flag indicating if the menu should be rendered lazily
`trigger` `React.ReactElement`	Element that is used as the trigger which will activate the dropdown on click.
`triggerIcon` `string \| null`	Flag indicating if the caret icon should be displayed on the right side. The default value is null

DropDown

DropDown.Action

DropDown.Caption

DropDown.Divider

DropDown.Group

DropDown.Help

DropDown.Item

DropDown.ItemList

DropDown.Menu

DropDown.Search

DropDown.Section

DropDownWithItems

DropDownWithDrilldown