Components
SelectPopover

SelectPopover

Popover box of Select

Optional props

asChild

Enable children composition

type
boolean
default
false

store

Object returned by the useSelectStore hook. If not provided, the closest SelectProvider component's context will be used.

type
SelectStore<SelectStoreValue>
default
null

resetOnEscape

Whether the select value should be reset to the value before the list got shown when Escape is pressed. This has effect only when setValueOnMove is true.

type
BooleanOrCallback<React.KeyboardEvent<HTMLElement>>
default
true

hideOnEnter

Whether the SelectList or SelectPopover components should be hidden when the user presses Enter or Space while the list element is focused and no item is active.

type
BooleanOrCallback<React.KeyboardEvent<HTMLElement>>
default
true

composite

Determines if the component should act as a composite widget. This prop needs to be set to false when merging various composite widgets where only one should function in that manner.

If disabled, this component will stop managing focus and keyboard navigation for its items and itself. Additionally, composite ARIA attributes won't be applied. These responsibilities should be taken over by another composite component.

Note: In most cases, this prop doesn't need to be set manually. For example, when composing Menu with Combobox or Select with Combobox, this prop will be set to false automatically on the Menu and SelectPopover components so the Combobox component can take over the composite widget responsibilities.

Live examples:

type
boolean
default
true

moveOnKeyPress

Determines whether the composite widget should move focus to an item when arrow keys are pressed, given that the composite element is focused and there's no active item.

Note: To entirely disable focus moving within a composite widget, you can use the focusOnMove prop instead. If you want to control the behavior only when arrow keys are pressed, where focusOnMove may not be applicable, this prop must be set on composite items as well.

type
BooleanOrCallback<React.KeyboardEvent<HTMLElement>>
default
true

focusOnMove

Determines if the active composite item should receive focus (or virtual focus if the virtualFocus option is enabled) when moving through items. This typically happens when navigating through items with arrow keys, but it can also happen when calling the move method directly.

Unlike the composite prop, this option doesn't disable the entire composite widget behavior. It only stops this component from managing focus when navigating through items.

Note: If you want to control the behavior only when arrow keys are pressed, use the moveOnKeyPress prop instead.

type
boolean
default
true

focusable

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

type
boolean
default
null

disabled

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don't support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples:

type
boolean
default
false

autoFocus

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples:

type
boolean
default
false

accessibleWhenDisabled

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls.

Live examples:

type
boolean
default
null

onFocusVisible

Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the data-focus-visible attribute.

Note: For this prop to work, the focusable prop must be set to true, if it's not set by default.

Live examples:

type
BivariantCallback<(event: React.SyntheticEvent<HTMLElement, Event>) => void>
default
null

render

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

type
RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any>
undefined; }>
React.ReactElement<any, string
React.JSXElementConstructor<any>>
default
null

typeahead

When enabled, pressing printable character keys will move focus to the next composite item that starts with the entered characters.

type
boolean
default
true

alwaysVisible

Determines whether the content element should remain visible even when the open state is false. If this prop is set to true, the hidden prop and the display: none style will not be applied, unless explicitly set otherwise.

This prop is particularly useful when using third-party animation libraries such as Framer Motion or React Spring, where the element needs to be visible for exit animations to work.

Live examples:

type
boolean
default
false

open

Controls the open state of the dialog. This is similar to the open attribute on native dialog elements.

Live examples:

type
boolean
default
null

wrapperProps

Props that will be passed to the popover wrapper element. This element will be used to position the popover.

Live examples:

type
React.HTMLAttributes<HTMLDivElement>
default
null

fixed

Whether the popover has position: fixed or not.

type
boolean
default
false

gutter

The distance between the popover and the anchor element.

Live examples:

type
number
default
0

shift

The skidding of the popover along the anchor element. Can be set to negative values to make the popover shift to the opposite side.

Live examples:

type
number
default
0

flip

Controls the behavior of the popover when it overflows the viewport:

  • If a boolean, specifies whether the popover should flip to the opposite side when it overflows.
  • If a string, indicates the preferred fallback placements when it overflows. The placements must be spaced-delimited, e.g. "top left".

Live examples:

type
string
boolean
default
true

slide

Whether the popover should slide when it overflows.

type
boolean
default
true

overlap

Whether the popover can overlap the anchor element when it overflows.

Live examples:

type
boolean
default
false

sameWidth

Whether the popover should have the same width as the anchor element. This will be exposed to CSS as --popover-anchor-width.

type
boolean
default
false

fitViewport

Whether the popover should fit the viewport. If this is set to true, the popover wrapper will have maxWidth and maxHeight set to the viewport size. This will be exposed to CSS as --popover-available-width and --popover-available-height.

Live examples:

type
boolean
default
false

arrowPadding

The minimum padding between the arrow and the popover corner.

type
number
default
4

overflowPadding

The minimum padding between the popover and the viewport edge. This will be exposed to CSS as --popover-overflow-padding.

Live examples:

type
number
default
8

getAnchorRect

Function that returns the anchor element's DOMRect. If this is explicitly passed, it will override the anchor getBoundingClientRect method.

Live examples:

type
((anchor: HTMLElement
null) => AnchorRect
null)
default
null

updatePosition

A callback that will be called when the popover needs to calculate its position. This will override the internal updatePosition function. The original updatePosition function will be passed as an argument, so it can be called inside the callback to apply the default behavior.

Live examples:

type
((props: { updatePosition: () => Promise<void>; }) => void
Promise<void>)
default
null

onClose

This is an event handler prop triggered when the dialog's close event is dispatched. The close event is similar to the native dialog close event. The only difference is that this event can be canceled with event.preventDefault(), which will prevent the dialog from hiding.

It's important to note that this event only fires when the dialog store's open state is set to false. If the controlled open prop value changes, or if the dialog's visibility is altered in any other way (such as unmounting the dialog without adjusting the open state), this event won't be triggered.

Live examples:

type
((event: Event) => void)
default
null

modal

Determines whether the dialog is modal. Modal dialogs have distinct states and behaviors:

  • The portal and preventBodyScroll props are set to true. They can still be manually set to false.
  • When using the Heading or DialogHeading components within the dialog, their level will be reset so they start with h1.
  • A visually hidden dismiss button will be rendered if the DialogDismiss component hasn't been used. This allows screen reader users to close the dialog.
  • When the dialog is open, element tree outside it will be inert.

Live examples:

type
boolean
default
true

backdrop

Determines whether there will be a backdrop behind the dialog. On modal dialogs, this is true by default. Besides a boolean, this prop can also be a React component or JSX element that will be rendered as the backdrop.

Note: If a custom component is used, it must accept ref and spread all props to its underlying DOM element, the same way a native element would.

Live examples:

type
boolean
React.ReactElement<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, ref> & { ref?: ((instance: HTMLDivElement
null) => void)
... 2 more ...
undefined; }, string
React.JSXElementConstructor<...>>
React.ElementType<...>
default
null

hideOnEscape

Determines if the dialog will hide when the user presses the Escape key.

This prop can be either a boolean or a function that accepts an event as an argument and returns a boolean. The event object represents the keydown event that initiated the hide action, which could be either a native keyboard event or a React synthetic event.

Note: When placing Ariakit dialogs inside third-party dialogs, using event.stopPropagation() within this function will stop the event from reaching the third-party dialog, closing only the Ariakit dialog.

type
BooleanOrCallback<KeyboardEvent
React.KeyboardEvent<Element>>
default
true

hideOnInteractOutside

Determines if the dialog should hide when the user clicks or focuses on an element outside the dialog.

This prop can be either a boolean or a function that takes an event as an argument and returns a boolean. The event object represents the event that triggered the action, which could be a native event or a React synthetic event of various types.

Live examples:

type
BooleanOrCallback<Event
React.SyntheticEvent<Element, Event>>
default
true

getPersistentElements

When a dialog is open, the elements outside of it are disabled to prevent interaction if the dialog is modal. For non-modal dialogs, interacting with elements outside the dialog prompts it to close.

This function allows you to return an iterable collection of elements that will be considered as part of the dialog, thus excluding them from this behavior.

Note: The elements returned by this function must exist in the DOM when the dialog opens.

Live examples:

type
(() => Iterable<Element>)
default
null

preventBodyScroll

Determines whether the body scrolling will be prevented when the dialog is shown. This is automatically set to true when the dialog is modal. You can disable this prop if you want to implement your own logic.

type
boolean
default
null

autoFocusOnShow

Determines whether an element inside the dialog will receive focus when the dialog is shown. By default, this is usually the first tabbable element in the dialog or the dialog itself. The initialFocus prop can be used to set a different element to receive focus.

Live examples:

type
BooleanOrCallback<HTMLElement
null>
default
true

autoFocusOnHide

Determines whether an element outside of the dialog will be focused when the dialog is hidden if another element hasn't been focused in the action of hiding the dialog (for example, by clicking or tabbing into another tabbable element outside of the dialog).

By default, this is usually the disclosure element. The finalFocus prop can be used to define a different element to be focused.

Live examples:

type
BooleanOrCallback<HTMLElement
null>
default
true

initialFocus

Specifies the element that will receive focus when the dialog is first opened. It can be an HTMLElement or a React.RefObject with an HTMLElement.

If autoFocusOnShow is set to false, this prop will have no effect. If left unset, the dialog will attempt to determine the initial focus element in the following order:

  1. A Focusable element with an autoFocus prop.
  2. The first tabbable element inside the dialog.
  3. The first focusable element inside the dialog.
  4. The dialog element itself.
type
HTMLElement
React.RefObject<HTMLElement>
null
default
null

finalFocus

Determines the element that will receive focus once the dialog is closed, provided that no other element has been focused while the dialog was being hidden (e.g., by clicking or tabbing into another tabbable element outside of the dialog).

  • If autoFocusOnHide is set to false, this prop will have no effect.
  • If left unset, the element that was focused before the dialog was opened will be focused again.
type
HTMLElement
React.RefObject<HTMLElement>
null
default
null

preserveTabOrder

When enabled, preserveTabOrder will keep the DOM element's tab order the same as the order in which the underlying Portal component was mounted in the React tree.

If the preserveTabOrderAnchor prop is provided, the tab order will be preserved relative to that element.

type
boolean
default
false

preserveTabOrderAnchor

An anchor element for maintaining the tab order when preserveTabOrder prop is enabled. The tab order will be kept relative to this element.

By default, the tab order is kept relative to the original location in the React tree where the underlying Portal component was mounted.

type
Element
null
default
null

portalRef

portalRef is similar to ref but is scoped to the portal node. It's useful when you need to be informed when the portal element is appended to the DOM or removed from the DOM.

Live examples:

type
React.RefCallback<HTMLElement>
React.MutableRefObject<HTMLElement
null>
default
null

portal

Determines whether the element should be rendered as a React Portal.

Live examples:

type
boolean
default
true

portalElement

An HTML element or a memoized callback function that returns an HTML element to be used as the portal element. By default, the portal element will be a div element appended to the document.body.

Live examples:

type
HTMLElement
((element: HTMLElement) => HTMLElement
null)
null
default
null

unmountOnHide

When set to true, the content element will be unmounted and removed from the DOM when it's hidden.

Live examples:

type
boolean
default
false