useListNavigation

import {useListNavigation} from '@floating-ui/react';

• See FloatingList for creating composable children API components.
• See Composite for list navigation outside of floating element contexts.

Usage

This Hook returns event handler props and ARIA attribute props.

To use it, pass it the context object returned from useFloating(), and then feed its result into the useInteractions() array. The returned prop getters are then spread onto the elements for rendering. getItemProps() is spread to each list item.

The listRef holds an array of HTML elements. The activeIndex determines which index of the list is currently active (focused or highlighted).

When using real DOM focus (default), the list items must be focusable and should have an appropriate role prop based on the role of the floating element.

function App() {
  const [activeIndex, setActiveIndex] = useState(null);
 
  const {refs, floatingStyles, context} = useFloating({
    open: true,
  });
 
  const listRef = useRef([]);
 
  const listNavigation = useListNavigation(context, {
    listRef,
    activeIndex,
    onNavigate: setActiveIndex,
  });
 
  const {getReferenceProps, getFloatingProps, getItemProps} =
    useInteractions([listNavigation]);
 
  const items = ['one', 'two', 'three'];
 
  return (
    <>
      <div ref={refs.setReference} {...getReferenceProps()}>
        Reference element
      </div>
      <div
        ref={refs.setFloating}
        style={floatingStyles}
        {...getFloatingProps()}
      >
        {items.map((item, index) => (
          <div
            key={item}
            // Make these elements focusable using a roving tabIndex.
            tabIndex={activeIndex === index ? 0 : -1}
            ref={(node) => {
              listRef.current[index] = node;
            }}
            {...getItemProps()}
          >
            {item}
          </div>
        ))}
      </div>
    </>
  );
}

Examples

• Select
• Combobox

Using with FloatingFocusManager

useListNavigation() and <FloatingFocusManager> both manage focus but in different ways. To ensure they work together properly, the initial point of focus needs to be considered.

The focus manager by default focuses the first tabbable (not focusable) element inside of the floating element. If none are, it falls back to the floating element itself. This allows keydown events to work for pointer input (e.g. open with mouse, then start navigating with arrow keys).

1. For a combobox, where the input should keep focus, set it to -1 so focus doesn’t move at all:

<FloatingFocusManager context={context} initialFocus={-1}>
  {/* floating element */}
</FloatingFocusManager>

2. For other types of components, like a menu or a select, where you want focus to move inside the floating element, the default value works, but make sure your list items aren’t tabbable if the activeIndex is null.

// Not focusable, not tabbable.
<div />
// Tabbable and focusable.
<div tabIndex={0} />
// Not tabbable, but focusable.
<div tabIndex={-1} />

A roving tabIndex is the recommended strategy:

<div tabIndex={activeIndex === index ? 0 : -1} />

Props

interface UseListNavigationProps {
  listRef: React.MutableRefObject<Array<HTMLElement | null>>;
  activeIndex: number | null;
  onNavigate?(index: number | null): void;
  enabled?: boolean;
  selectedIndex?: number | null;
  loop?: boolean;
  nested?: boolean;
  rtl?: boolean;
  virtual?: boolean;
  virtualItemRef?: React.MutableRefObject<HTMLElement | null>;
  allowEscape?: boolean;
  orientation?: 'vertical' | 'horizontal' | 'both';
  cols?: number;
  focusItemOnOpen?: 'auto' | boolean;
  focusItemOnHover?: boolean;
  openOnArrowKeyDown?: boolean;
  disabledIndices?: Array<number>;
  scrollItemIntoView?: boolean | ScrollIntoViewOptions;
  itemSizes?: Dimensions[];
  dense?: boolean;
}

listRef

default: empty list

A ref that holds an array of list items. You can assign each item in the array by its index like so:

const options = ['one', 'two', 'three'];
const listRef = useRef([]);
 
return options.map((option, index) => (
  <li
    key={option}
    ref={(node) => {
      listRef.current[index] = node;
    }}
  >
    {option}
  </li>
));

activeIndex

default: null

The currently active (i.e. highlighted or focused) item index, which may or may not be selected.

const [activeIndex, setActiveIndex] = useState(null);
 
useListNavigation(context, {
  activeIndex,
});

onNavigate

default: no-op

Callback invoked when the user navigates, passed in the current activeIndex.

const [activeIndex, setActiveIndex] = useState(null);
 
useListNavigation(context, {
  onNavigate: setActiveIndex,
});

enabled

default: true

Conditionally enable/disable the Hook.

useListNavigation(context, {
  enabled: false,
});

selectedIndex

default: null

The currently selected item index, which may or may not be active.

This is the item shown in the trigger button/input.

const [selectedIndex, setSelectedIndex] = useState(null);
 
useListNavigation(context, {
  selectedIndex,
});

loop

default: false

Determines whether focus should loop around when navigating past the first or last item.

useListNavigation(context, {
  loop: true,
});

nested

default: false

If the list is nested within another one (e.g. a nested submenu), the navigation semantics change.

useListNavigation(context, {
  nested: true,
});

rtl

default: false

Whether the direction of the floating element’s navigation is in RTL layout.

useListNavigation(context, {
  rtl: true,
});

virtual

default: false

Whether the focus is virtual (using aria-activedescendant).

Use this if you need focus to remain on the reference element (such as an input), but allow arrow keys to navigate list items. This is common in autocomplete listbox components.

useListNavigation(context, {
  virtual: true,
});

virtualItemRef

default: undefined

When using virtual focus management, this holds a ref to the virtually-focused item.

This allows nested virtual navigation to be enabled, and lets you know when a nested element is virtually focused from the root reference handling the events.

const virtualItemRef = useRef(null);
useListNavigation(context, {
  virtualItemRef,
});

allowEscape

Determines whether focus can escape the list, such that nothing is selected after navigating beyond the boundary of the list. In some autocomplete/combobox components, this may be desired, as screen readers will return to the input.

useListNavigation(context, {
  loop: true,
  allowEscape: true,
});

orientation

default: 'vertical'

The orientation in which navigation occurs.

useListNavigation(context, {
  orientation: 'horizontal',
});

cols

default: 1

Specifies how many columns the list has (i.e., it’s a grid).

Use an orientation of 'horizontal' (e.g. for an emoji picker/date picker, where pressing ArrowRight or ArrowLeft can change rows), or 'both' (where the current row cannot be escaped with ArrowRight or ArrowLeft, only ArrowUp and ArrowDown).

useListNavigation(context, {
  // 4 columns, any number of rows
  cols: 4,
});

focusItemOnOpen

default: 'auto'

Whether to focus the item upon opening the floating element. 'auto' infers what to do based on the input type (keyboard vs. pointer), while a boolean value will force the value.

useListNavigation(context, {
  focusItemOnOpen: true,
});

focusItemOnHover

default: true

Whether hovering an item synchronizes the focus.

useListNavigation(context, {
  focusItemOnHover: false,
});

openOnArrowKeyDown

default: true

Whether pressing an arrow key on the navigation’s main axis opens the floating element.

useListNavigation(context, {
  openOnArrowKeyDown: false,
});

disabledIndices

default: undefined

By default elements with either a disabled or aria-disabled attribute are skipped in the list navigation — however, this requires the items to be rendered.

This prop allows you to manually specify indices which should be disabled, overriding the default logic.

For Windows-style select menus, where the menu does not open when navigating via arrow keys, specify an empty array.

useListNavigation(context, {
  disabledIndices: [0, 3],
});

scrollItemIntoView

default: true | ScrollIntoViewOptions

Whether to scroll the active item into view when navigating. The default value uses nearest options.

useListNavigation(context, {
  scrollItemIntoView: false,
});

itemSizes

default: undefined

Only for grid navigation, an array of Dimensions objects, which specify the width (number of columns) and height (number of rows) of each item, so the navigation algorithm can take the variable sizes into account. If not specified, every item will be treated as if it has a size of 1 row and 1 column.

useListNavigation(context, {
  itemSizes: [
    {width: 2, height: 2},
    {width: 1, height: 3},
  ],
});

dense

default: false

Only for grid navigation, determines if the grid positioning algorithm should follow CSS Grid’s auto-flow dense algorithm.

useListNavigation(context, {
  dense: true,
});