Value components

Read and render a single Ariakit value from a provider, store, or item context without adding any element of your own.

Overview

A value component reads one specific value from a provider, an explicit store, or the closest item context and renders it. Unlike most Ariakit components, it:

reads a single value from the nearest provider, an explicit store prop, or the closest item context
adds no element of its own, though it may return text or arbitrary JSX
exposes the value directly or through a children render function
does not accept HTML props such as className, style, or ref, because it has no element to receive them

The stable public value components are ComboboxInputValue, ComboboxSelectedValue, and ComboboxItemSelected, all exported from @ariakit/react.

This pattern is not inherently uncontrolled. Value components work with both controlled and uncontrolled providers and stores. Their main benefit is exposing state close to the JSX that needs it, without creating or passing a store solely for that purpose.

Rendering a value directly

In its shortest form, a value component renders the current value as-is. No wrapper element is added around it, so it sits directly wherever you place it:

<ComboboxProvider defaultSelectedValue="Apple">
  <ComboboxSelect>
    <ComboboxSelectedValue fallback="Choose a fruit" />
  </ComboboxSelect>
  <ComboboxPopover>
    <ComboboxItem value="Apple" />
    <ComboboxItem value="Banana" />
    <ComboboxItem value="Orange" />
  </ComboboxPopover>
</ComboboxProvider>
<ComboboxProvider defaultSelectedValue="Apple">
  <ComboboxSelect>
    <ComboboxSelectedValue fallback="Choose a fruit" />
  </ComboboxSelect>
  <ComboboxPopover>
    <ComboboxItem value="Apple" />
    <ComboboxItem value="Banana" />
    <ComboboxItem value="Orange" />
  </ComboboxPopover>
</ComboboxProvider>

ComboboxSelectedValue accepts a fallback prop that's used when the current selected value is an empty string or empty array.

Rendering custom JSX

Pass a function as children to transform the value before rendering it. The function receives the current value and returns whatever you want to render:

<ComboboxProvider>
  <Combobox />
  <ComboboxInputValue>
    {(value) => <output>Current value: {value || "empty"}</output>}
  </ComboboxInputValue>
</ComboboxProvider>
<ComboboxProvider>
  <Combobox />
  <ComboboxInputValue>
    {(value) => <output>Current value: {value || "empty"}</output>}
  </ComboboxInputValue>
</ComboboxProvider>

Returning the raw value isn't always useful. For example, a multi-select renders its values with no separators between them. Use a function child whenever the value needs formatting or custom UI.

Rendering item state

Item-scoped value components read state from the closest item instead of the provider or store. For example, use ComboboxItemSelected inside a ComboboxItem to render custom UI based on whether that item is selected:

<ComboboxItem value="Apple">
  <ComboboxItemSelected>
    {(selected) => (selected ? <CheckIcon /> : null)}
  </ComboboxItemSelected>
  Apple
</ComboboxItem>
<ComboboxItem value="Apple">
  <ComboboxItemSelected>
    {(selected) => (selected ? <CheckIcon /> : null)}
  </ComboboxItemSelected>
  Apple
</ComboboxItem>

The children function is required because a raw boolean doesn't produce visible output in React. It receives the current selected state and re-runs whenever that state changes.

Choosing an API

Value components are one of several ways to work with Ariakit state. Pick based on what the surrounding code needs:

Use a value component when a small section of JSX only needs one exposed value.
Use controlled provider props when application state must own, persist, validate, or share the value. See Component providers.
Use useStoreState when a component needs arbitrary store fields, multiple values, or a computed selector.
Use store.getState() for event-only reads that shouldn't trigger a re-render.
Use context hooks for lower-level descendant components that need access to the complete store.

Next steps

Continue reading our Guide to learn more about Ariakit:

Component providersProvide state to Ariakit components using a simple wrapper that supports controlled and uncontrolled props.

Component storesAccess and manipulate the state of Ariakit components in a performant way through component stores.