---
name: Composite
package: '@wordpress/components'
category: Utilities
status: stable
canonical: 'https://system.automattic.design/components/composite/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-composite--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/composite'
---

# Composite

Renders a widget based on the WAI-ARIA [`composite`](https://w3c.github.io/aria/#composite)
role, which provides a single tab stop on the page and arrow key navigation
through the focusable descendants.

```tsx
import { Composite } from '@wordpress/components';
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `activeId` | `string \| null \| undefined` | — | The current active item `id`. The active item is the element within the composite widget that has either DOM or virtual focus (in case the `virtualFocus` prop is enabled). - `null` represents the base composite element (the one with a [composite   role](https://w3c.github.io/aria/#composite)). Users will be able to   navigate out of it using arrow keys. - If `activeId` is initially set to `null`, the base composite element   itself will have focus and users will be able to navigate to it using   arrow keys. |
| `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. |
| `setActiveId` | `(activeId: string \| null \| undefined) => void` | — | A callback that gets called when the `activeId` state changes. |
| `focusLoop` | `boolean \| Orientation \| undefined` | `false` | Determines how the focus behaves when the user reaches the end of the composite widget.<br>On one-dimensional composite widgets: - `true` loops from the last item to the first item and vice-versa. - `horizontal` loops only if `orientation` is `horizontal` or not set. - `vertical` loops only if `orientation` is `vertical` or not set. - If `activeId` is initially set to `null`, the composite element will   be focused in between the last and first items.<br>On two-dimensional composite widgets (ie. 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 `activeId` is initially set to `null`, vertical loop will have no   effect as moving down from the last row or up from the first row will   focus on the composite element. - If `focusWrap` matches the value of `focusLoop`, 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. |
| `focusWrap` | `boolean \| Orientation \| undefined` | `false` | **Works only on two-dimensional composite widgets**.<br>If enabled, moving to the next item from the last one in a row or column will focus on 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 of `focusWrap`, 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 composite widgets**.<br>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. |
| `virtualFocus` | `boolean` | `false` | If enabled, the composite element will act as an [`aria-activedescendant`](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant) container instead of [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex). DOM focus will remain on the composite element while its items receive virtual focus.<br>In both scenarios, the item in focus will carry the `data-active-item` attribute. |
| `orientation` | `"both" \| "horizontal" \| "vertical"` | `'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.<br>It doesn't have any effect on two-dimensional composites. |
| `rtl` | `boolean` | `isRTL()` | Controls how the previous and next items are determined. If `rtl` is set to `true`, they will be inverted.<br>This only affects the composite widget behavior. You still need to set `dir="rtl"` on HTML/CSS. |
| `render` | `ReactElement<any, string \| JSXElementConstructor<any>> \| RenderProp<HTMLAttributes<any> & { ref?: Ref<any> \| undefined; }> \| undefined` | — | 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. |
| `focusable` | `boolean` | — | Makes the component a focusable element. When this element gains keyboard focus, it gets a `data-focus-visible` attribute and triggers the `onFocusVisible` prop. The component supports the `disabled` prop even for those elements not supporting the native `disabled` attribute. Disabled elements may be still accessible via keyboard by using the `accessibleWhenDisabled` prop. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability. |
| `disabled` | `boolean` | `false` | 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.<br>This feature can be combined with the `accessibleWhenDisabled` prop to make disabled elements still accessible via keyboard.<br>**Note**: For this prop to work, the `focusable` prop must be set to `true`, if it's not set by default. |
| `accessibleWhenDisabled` | `boolean` | — | Indicates whether the element should be focusable even when it is `disabled`.<br>This is important when discoverability is a concern. For example:<br>> 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.<br>Learn more on [Focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols). |
| `onFocusVisible` | `BivariantCallback<(event: SyntheticEvent<HTMLElement, Event>) => void>` | — | 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.<br>**Note**: For this prop to work, the `focusable` prop must be set to `true` if it's not set by default. |
| `children` | `ReactNode` | — | The contents of the component. |


## Examples

### Default

```tsx
const Default = () => <Composite>(<>
        <Composite.Item>Item one</Composite.Item>
        <Composite.Item>Item two</Composite.Item>
        <Composite.Item>Item three</Composite.Item>
    </>)</Composite>;
```

### Groups

```tsx
const Groups = () => <Composite>(<>
        <Composite.Group>
            <Composite.GroupLabel>Group one</Composite.GroupLabel>
            <Composite.Item>Item 1.1</Composite.Item>
            <Composite.Item>Item 1.2</Composite.Item>
        </Composite.Group>
        <Composite.Group>
            <Composite.GroupLabel>Group two</Composite.GroupLabel>
            <Composite.Item>Item 2.1</Composite.Item>
            <Composite.Item>Item 2.1</Composite.Item>
        </Composite.Group>
    </>)</Composite>;
```

### Grid

```tsx
const Grid = () => <Composite role="grid" aria-label="Composite">(<>
        <Composite.Row role="row">
            <Composite.Item role="gridcell">Item A1</Composite.Item>
            <Composite.Item role="gridcell">Item A2</Composite.Item>
            <Composite.Item role="gridcell">Item A3</Composite.Item>
        </Composite.Row>
        <Composite.Row role="row">
            <Composite.Item role="gridcell">Item B1</Composite.Item>
            <Composite.Item role="gridcell">Item B2</Composite.Item>
            <Composite.Item role="gridcell">Item B3</Composite.Item>
        </Composite.Row>
        <Composite.Row role="row">
            <Composite.Item role="gridcell">Item C1</Composite.Item>
            <Composite.Item role="gridcell">Item C2</Composite.Item>
            <Composite.Item role="gridcell">Item C3</Composite.Item>
        </Composite.Row>
    </>)</Composite>;
```

### Hover

```tsx
const Hover = () => <Composite>(<>
        <Composite.Hover render={ <Composite.Item /> }>
            Hover item one
        </Composite.Hover>
        <Composite.Hover render={ <Composite.Item /> }>
            Hover item two
        </Composite.Hover>
        <Composite.Hover render={ <Composite.Item /> }>
            Hover item three
        </Composite.Hover>
    </>)</Composite>;
```

### Typeahead

```tsx
const Typeahead = () => <Composite render={<Composite.Typeahead />}>(<>
        <Composite.Item>Apple</Composite.Item>
        <Composite.Item>Banana</Composite.Item>
        <Composite.Item>Peach</Composite.Item>
    </>)</Composite>;
```

### With Slot Fill

```tsx
const WithSlotFill = () => <Composite>(<>
        <Composite.Item>Item one (direct child)</Composite.Item>
        <Slot />
        <Composite.Item>Item four (direct child)</Composite.Item>
    </>)</Composite>;
```

### With Tooltips

Combining the `Tooltip` and `Composite` component has a few caveats. And while there are a few ways to compose these two components, our recommendation is to render `Composite.Item` as a child of `Tooltip`.

```jsx
// 🔴 Does not work

</Tooltip>
```

```tsx
const WithTooltips = () => <Composite>(<>
        <Tooltip text="Tooltip one">
            <Composite.Item>Item one</Composite.Item>
        </Tooltip>
        <Tooltip text="Tooltip two">
            <Composite.Item>Item two</Composite.Item>
        </Tooltip>
        <Tooltip text="Tooltip three">
            <Composite.Item>Item three</Composite.Item>
        </Tooltip>
    </>)</Composite>;
```