Listbox Grid

Accessible, unstyled 2-D option grid (icon, color, and swatch pickers) with typed selection. The pure grid navigation (moveInGrid, gridMoveFromKey) stays internal to the family source so the subpath bundle keeps a single chunk order; source installs can import listbox-grid-model.ts directly.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { ListboxGrid, ListboxGridItem } from "@vizejs/ui/listbox-grid";

Or copy the source into your project with vize lib pull listbox-grid (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Single-select color swatch grid navigated with arrow keys in two dimensions. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import { ListboxGrid, ListboxGridItem } from "@vizejs/ui/listbox-grid";

const swatches = ["Crimson", "Coral", "Gold", "Olive", "Teal", "Navy", "Plum", "Slate"];
const color = ref<string | null>("Teal");
const labelId = useId();
</script>

<template>
  <div>
    <span :id="labelId">Label color</span>
    <ListboxGrid v-model="color" :columns="4" name="labelColor" :aria-labelledby="labelId">
      <ListboxGridItem v-for="swatch in swatches" :key="swatch" :value="swatch">
        {{ swatch }}
      </ListboxGridItem>
    </ListboxGrid>
    <output>Selected: {{ color ?? "none" }}</output>
  </div>
</template>

API

ListboxGrid<T, Multiple extends boolean = false>

Source: src/families/selection/listbox-grid/listbox-grid.vue

Props

Events

Slots

Exposed

ListboxGridItem<T>

Source: src/families/selection/listbox-grid/listbox-grid-item.vue

Props

Slots

Exposed

Behavior

Contract

ListboxGrid is a headless, strongly typed 2-D option grid for icon, color, swatch, and "rich select" pickers. listbox-grid.vue is generic over the value type T and a Multiple literal (T | null or readonly T[]), renders role="listbox" with aria-activedescendant, and keeps DOM focus on itself. listbox-grid-item.vue renders role="option" and registers with the shared collection registry, which also powers buffered typeahead. Arrow keys follow the visual grid through the pure moveInGrid helper; columns must match the consumer's CSS grid. Named grids submit one hidden input per selected value. No CSS ships.

Normative Behavior

SSR

Ids come from the deterministic-id primitive; server markup is byte-identical across isolated requests and hydrates without warnings (renders byte-identical ListboxGrid markup across isolated SSR requests, hydrates ListboxGrid without mismatches or node replacement).