Dropdown Menu

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

install	yarn add @clayui/drop-down
version	3.120.0

Stable 3.120.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
`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 ''

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.

DropDown

DropDown.Action

DropDown.Caption

DropDown.Divider

DropDown.Group

DropDown.Help

DropDown.Item

DropDown.ItemList

DropDown.Menu

DropDown.Search

DropDown.Section

DropDownWithItems

DropDownWithDrilldown