use-cycle-list

Cycle through a list with wrap-around navigation.


Package	`@vizejs/composable/use-cycle-list`
Own the source	`vize lib pull composable:use-cycle-list`
Runtime exports	`useCycleList`
Gzip budget	768 B

Usage

import { useCycleList } from "@vizejs/composable/use-cycle-list";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useCycleList`	state	experimental	safe	stable	reactive-scope	web, server, worker, native, desktop, terminal	—	—

API

`useCycleList`

Cycle through a list with wrap-around navigation. Non-empty tuple sources (["light", "dark", "system"] as const) yield a state typed as the element union; general arrays may be empty, so their state includes undefined. When the list changes, the cursor keeps the current item if it is still present and otherwise moves to fallbackIndex. Synchronous state: SSR-safe; the list watcher follows the owning scope.

function useCycleList<const List extends readonly [unknown, ...unknown[]]>( list: MaybeRefOrGetter<List>, options?: UseCycleListOptions<List[number]>, ): CycleList<List[number], List[number]>

const { state, next } = useCycleList(["light", "dark", "system"] as const);
next(); // "dark"

`useCycleList`

function useCycleList<Item>( list: MaybeRefOrGetter<readonly Item[]>, options?: UseCycleListOptions<Item>, ): CycleList<Item | undefined, Item>

`useCycleList`

function useCycleList<Item>( list: MaybeRefOrGetter<readonly Item[]>, options: UseCycleListOptions<Item> = {}, ): CycleList<Item | undefined, Item>

Types

`UseCycleListOptions`

Options for useCycleList.

Member	Type	Description
`initialValue`?	`Item`	Item selected initially.
`fallbackIndex`?	`number`	Index used when the current item is not in the list.
`getIndexOf`?	`(item: Item, list: readonly Item[]) => number`	Locate an item in the list, for example by id.

`CycleList`

Cursor over a list returned by useCycleList.

Member	Type	Description
`state`	`ShallowRef<Current>`	Current item. Writable: assigning moves the cursor to that item.
`index`	`WritableComputedRef<number>`	Current index. Writable: assigning wraps around the list.
`next`	`(steps?: number) => Current`	Move forward `steps` items (default `1`), wrapping around.
`prev`	`(steps?: number) => Current`	Move backward `steps` items (default `1`), wrapping around.
`go`	`(index: number) => Current`	Jump to `index`, wrapping around.
`list`	`Readonly<ShallowRef<readonly Item[]>>`	The list items, for convenience.