FloatingList

Provides the ability to create composable children APIs for list components, without needing to keep track of a list item index for useListNavigation or useTypeahead.

Manually specifying an index poses problems when wrapper tags surround list items, such as with grouping.

An example of a composable children API looks like the following, where <Select><Select> does not receive an array prop but rather children:

<Select>
  <OptionGroup label="Fruits">
    <Option>Apple</Option>
    <Option>Strawberry</Option>
    <Option>Banana</Option>
  </OptionGroup>
  <OptionGroup label="Vegetables">
    <Option>Carrot</Option>
    <Option>Green Peas</Option>
    <Option>Cauliflower</Option>
  </OptionGroup>
</Select>

<Select>
  <OptionGroup label="Fruits">
    <Option>Apple</Option>
    <Option>Strawberry</Option>
    <Option>Banana</Option>
  </OptionGroup>
  <OptionGroup label="Vegetables">
    <Option>Carrot</Option>
    <Option>Green Peas</Option>
    <Option>Cauliflower</Option>
  </OptionGroup>
</Select>

Examples

Select with Composable Children

Usage

import {FloatingList, useListItem} from '@floating-ui/react';

import {FloatingList, useListItem} from '@floating-ui/react';

FloatingList

This component is a context provider that receives two props:

elementsRef — useListNavigation()useListNavigation()’s listReflistRef prop (array of elements).
labelsRef — useTypeahead()useTypeahead()’s listReflistRef prop (array of strings; optional).

const elementsRef = useRef([]);
const labelsRef = useRef([]);
 
const listNav = useListNavigation(context, {
  listRef: elementsRef,
});
const typeahead = useTypeahead(context, {
  listRef: labelsRef,
});
 
return (
  <FloatingList elementsRef={elementsRef} labelsRef={labelsRef}>
    {/* floating element with list item children */}
  </FloatingList>
);

const elementsRef = useRef([]);
const labelsRef = useRef([]);
 
const listNav = useListNavigation(context, {
  listRef: elementsRef,
});
const typeahead = useTypeahead(context, {
  listRef: labelsRef,
});
 
return (
  <FloatingList elementsRef={elementsRef} labelsRef={labelsRef}>
    {/* floating element with list item children */}
  </FloatingList>
);

useListItem

This hook is used to register a list item and its index (DOM position) in the FloatingList. It returns two properties: refref and indexindex.

function Option() {
  const {activeIndex} = useSelectContext();
  const {ref, index} = useListItem();
 
  const isActive = activeIndex === index;
 
  return <div ref={ref} tabIndex={isActive ? 0 : -1} />;
}

function Option() {
  const {activeIndex} = useSelectContext();
  const {ref, index} = useListItem();
 
  const isActive = activeIndex === index;
 
  return <div ref={ref} tabIndex={isActive ? 0 : -1} />;
}

The hook optionally accepts a label prop, which is used to determine the string that can be matched with typeahead:

function Option({label}) {
  const {activeIndex} = useSelectContext();
  const {ref, index} = useListItem({
    label,
  });
 
  // ...
}

function Option({label}) {
  const {activeIndex} = useSelectContext();
  const {ref, index} = useListItem({
    label,
  });
 
  // ...
}

The label can be nullnull for disabled items, which will be ignored for typeahead.