Code examples
Optional Props
activeId
string | null | undefined
The current focused item id
.
null
focuses the base composite element and users will be able to navigate out of it using arrow keys.If
activeId
is initially set tonull
, theincludesBaseElement
prop will also default totrue
, which means the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
children
React.ReactNode
defaultActiveId
string | null | undefined
The composite item id that should be active by default when the composite
widget is rendered. If null
, the composite element itself will have focus
and users will be able to navigate to it using arrow keys. If undefined
,
the first enabled item will be focused.
defaultItems
T[] | undefined = []
The defaut value for the items
state.
focusLoop
boolean | Orientation = false
Determines how the focus behaves when the user reaches the end of the composite widget.
On one-dimensional composites:
true
loops from the last item to the first item and vice-versa.horizontal
loops only iforientation
ishorizontal
or not set.vertical
loops only iforientation
isvertical
or not set.If
includesBaseElement
is set totrue
(oractiveId
is initially set tonull
), the composite element will be focused in between the last and first items.
On two-dimensional composites (when using CompositeRow
):
true
loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.horizontal
loops only from the last row item to the first item in the same row.vertical
loops only from the last column item to the first item in the column row.If
includesBaseElement
is set totrue
(oractiveId
is initially set tonull
), vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.If
focusWrap
matches the value offocusLoop
, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
focusShift
boolean = false
Works only on two-dimensional composites. If enabled, moving up or down when there's no next item or when the next item is disabled will shift to the item right before it.
focusWrap
boolean | Orientation = false
Works only on two-dimensional composites. If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.
true
wraps between rows and columns.horizontal
wraps only between rows.vertical
wraps only between columns.If
focusLoop
matches the value offocusWrap
, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
includesBaseElement
boolean = false
Indicates whether the composite element should be included in the focus order.
items
T[]
Lists all the items with their meta data. This state is automatically
updated when an item is registered or unregistered with the registerItem
function.
orientation
Orientation = "both"
Defines the orientation of the composite widget. If the composite has a
single row or column (one-dimensional), the orientation
value determines
which arrow keys can be used to move focus:
both
: all arrow keys work.horizontal
: only left and right arrow keys work.vertical
: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
rtl
boolean = false
Determines how the next
and previous
functions will behave. If rtl
is
set to true
, they will be inverted. This only affects the composite
widget behavior. You still need to set dir="rtl"
on HTML/CSS.
setActiveId
((activeId: string | null | undefined) => void) | undefined
A callback that gets called when the activeId
state changes.
Code examples
const [activeId, setActiveId] = useState(null);
setItems
BivariantCallback<(items: T[]) => void> | undefined
A callback that gets called when the items
state changes.
Code examples
const [items, setItems] = useState([]);
store
Store<Partial<S>> | undefined
Another store object that will be kept in sync with the original store.
Live examples
virtualFocus
boolean = false
If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite element while its items receive virtual focus.
Live examples
Follow updates
Join 1,000+ subscribers and receive monthly updates with the latest improvements on API Reference.