createSingle

Extends createSelection to enforce single-item selection, automatically clearing the previous selection.

Copy Markdown

Stable Intermediate Jun 29, 2026

Usage

The createSingle composable is used when you have a collection of items but want to allow only one to be selected at any time.

import { createSingle } from '@vuetify/v0'

const single = createSingle()

// Register items first
single.register({ id: 'apple', value: 'Apple' })
single.register({ id: 'banana', value: 'Banana' })

// Select by ID
single.select('apple')
console.log(single.selectedId.value) // 'apple'
console.log(single.selectedValue.value) // 'Apple'

// Selecting a new item automatically clears the previous selection
single.select('banana')
console.log(single.selectedId.value) // 'banana' (replaces apple)

Context / DI

Use createSingleContext to share a single-selection instance across a component tree:

import { createSingleContext } from '@vuetify/v0'

export const [useTabSelection, provideTabSelection, tabSelection] =
  createSingleContext({ namespace: 'my:tabs', mandatory: true })

// In parent component
provideTabSelection()

// In child component
const selection = useTabSelection()
selection.select('tab-home')

Architecture

The createSingle composable is comprised of the following hierarchy:

Reactivity

Single-selection state is always reactive. All computed properties update automatically when the selection changes.

Property/Method	Reactive	Notes
`selectedId`		Computed from `selectedIds`
`selectedItem`		Computed from `selectedId`
`selectedValue`		Computed from `selectedItem`
`selectedIndex`		Computed from `selectedItem`
ticket `isSelected`		Computed from `selectedIds`

Tip

Perfect for UI controls selectedId, selectedValue, and selectedIndex work directly in templates without any extra setup.

A single-selection color theme switcher built entirely from createSingle. The composable owns the palette data and registers each theme as a ticket; clicking a swatch selects it exclusively and automatically deselects the previous choice, so the preview panel always reflects exactly one active palette. State lives in useThemePicker.ts, the swatch grid renders in ThemeSwatches.vue, and the entry file wires them together with a live preview and a state readout.

The example leans on three parts of the API working together. onboard() bulk-registers the five themes up front and returns one ticket per item, so the swatch component iterates tickets directly — calling ticket.select() and reading ticket.isSelected without routing back through the parent instance. mandatory: true keeps the selection sticky: once a theme is active, clicking it again is a no-op, guaranteeing the preview never renders an empty state. seek('first')?.select() preselects the first item on mount so the UI starts valid rather than blank, and the composable re-exports selectedValue, selectedId, selectedIndex, and size as flat derived refs so consumers never reach into the underlying instance.

Reach for this whenever a fixed set of mutually exclusive options needs the selected value — not just its id — reactively available for rendering: theme pickers, density toggles, segmented controls. The trade-off of mandatory is that there is no “nothing selected” state; if you need one, omit it and guard the consumer on selectedValue being undefined. For ordered next/prev navigation over the same selection, see createStep; for the multi-select parent, see createSelection.

File	Role
`useThemePicker.ts`	Owns the theme data and the `createSingle` instance; exposes tickets and flat derived selection refs
`ThemeSwatches.vue`	Renders the swatch grid, selecting a theme on click via `ticket.select()`
`theme-picker.vue`	Entry point — wires the composable to the swatches, live preview, and state readout