Value components

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

Overview

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

reads a single value from the nearest provider or from an explicit store prop
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 SelectValue and ComboboxValue, both 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:

<SelectProvider defaultValue="Apple">
  <Select>
    <SelectValue fallback="Choose a fruit" />
    <SelectArrow />
  </Select>
  <SelectPopover>
    <SelectItem value="Apple" />
    <SelectItem value="Banana" />
    <SelectItem value="Orange" />
  </SelectPopover>
</SelectProvider>
<SelectProvider defaultValue="Apple">
  <Select>
    <SelectValue fallback="Choose a fruit" />
    <SelectArrow />
  </Select>
  <SelectPopover>
    <SelectItem value="Apple" />
    <SelectItem value="Banana" />
    <SelectItem value="Orange" />
  </SelectPopover>
</SelectProvider>

SelectValue accepts a fallback prop that's used when the current 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 />
  <ComboboxValue>
    {(value) => <output>Current value: {value || "empty"}</output>}
  </ComboboxValue>
</ComboboxProvider>
<ComboboxProvider>
  <Combobox />
  <ComboboxValue>
    {(value) => <output>Current value: {value || "empty"}</output>}
  </ComboboxValue>
</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.

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.