createSingle

A composable that extends useSelection to enforce single-item selection. Automatically clears the previous selection before selecting a new item, ensuring only one item is selected at any time.

Copy Page as Markdown

100% coverage

Usage

The useSingle 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) // 'apple'
console.log(single.selectedValue) // 'Apple'

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

Architecture

The useSingle composable is comprised of the following hierarchy:

API Reference

The following API details are for the createSingle composable.

Creates a new single selection instance that enforces only one selected item at a time. Extends `createSelection` by automatically clearing previous selections when a new item is selected. Adds computed singular properties: `selectedId`, `selectedItem`, `selectedIndex`, `selectedValue`.

createSingleContext

(_options?: SingleContextOptions) => ContextTrinity<E>

Creates a new single selection context.

useSingle

(namespace?: string) => E

Returns the current single selection instance.

Options

events

boolean

Enable event emission for registry operations

Default: false

disabled

MaybeRef<boolean>

When true, the entire selection instance is disabled.

enroll

boolean

When true, newly registered items are automatically selected if not disabled. Useful for pre-selecting items in multi-select scenarios.

mandatory

boolean | "force"

Controls mandatory selection behavior: - `false` (default): No mandatory selection enforcement - `true`: Prevents deselecting the last selected item (user must always have one selected) - `'force'`: Automatically selects the first non-disabled item on registration

multiple

boolean

When true, treats the selection as an array

Properties

collection

ReadonlyMap<ID, Z>

The collection of tickets in the registry

size

number

The number of tickets in the registry

selectedIds

Reactive<Set<ID>>

Set of selected ticket IDs

selectedItems

ComputedRef<Set<Z>>

Set of selected ticket instances

selectedValues

ComputedRef<Set<unknown>>

Set of selected ticket values

disabled

MaybeRef<boolean>

Disable state for the entire selection instance

selectedId

ComputedRef<any>

selectedIndex

ComputedRef<number>

selectedItem

ComputedRef<Z>

selectedValue

ComputedRef<Z["value"]>

Methods

clear

() => void

Clear the entire registry

has

(id: ID) => boolean

Check if a ticket exists by ID

keys

() => ID[]

Get all registered IDs

browse

(value: unknown) => ID[] | undefined

Browse for an ID(s) by value

lookup

(index: number) => ID | undefined

lookup a ticket by index number

get

(id: ID) => Z | undefined

Get a ticket by ID

upsert

(id: ID, ticket?: Partial<Z>) => Z

Update or insert a ticket by ID

values

() => Z[]

Get all values of registered tickets

entries

() => [ID, Z][]

Get all entries of registered tickets

register

(ticket?: Partial<Z>) => Z

unregister

(id: ID) => void

Unregister an ticket by ID

reindex

() => void

Reset the index directory and update all tickets

seek

(direction?: "first" | "last", from?: number, predicate?: (ticket) => boolean) => Z | undefined

Seek for a ticket based on direction and optional predicate

on

(event: string, cb: RegistryEventCallback) => void

Listen for registry events

off

(event: string, cb: RegistryEventCallback) => void

Stop listening for registry events

emit

(event: string, data: unknown) => void

Emit an event with data

dispose

() => void

Clears the registry and removes all listeners

onboard

(registrations: Partial<Z>[]) => Z[]

Onboard multiple tickets at once

offboard

(ids: ID[]) => void

Offboard multiple tickets at once

batch

<R>(fn: () => R) => R

Execute operations in a batch, deferring cache invalidation and event emission until complete

reset

() => void

Clear all selected IDs and reindexes

select

(id: ID) => void

Select a ticket by ID (Toggle ON)

unselect

(id: ID) => void

Unselect a ticket by ID (Toggle OFF)

toggle

(id: ID) => void

Toggles a ticket ON and OFF by ID

selected

(id: ID) => boolean

Check if a ticket is selected by ID

mandate

() => void

Mandates selected ID based on "mandatory" Option