# @vuetify/v0 - Complete Documentation

> Headless Vue 3 UI primitives and composables for building modern applications and design systems.

---

# Contributing
URL: https://0.vuetifyjs.com/introduction/contributing

# Contributing

Thank you for your interest in contributing to Vuetify0! This guide will help you get started.

## Getting Started

Before contributing, please:

1. Read the [Getting Started](/introduction/getting-started) guide to understand the project
2. Review existing [issues](https://github.com/vuetifyjs/0/issues)
3. Join our [Discord community](https://community.vuetifyjs.com) for questions

## Reporting Issues

### Bug Reports

When reporting bugs, please include:

- A clear, descriptive title
- Steps to reproduce the issue
- Expected vs actual behavior
- Browser and OS information
- A minimal reproduction (preferably a link to a repo or CodeSandbox)

### Feature Requests

For new features:

- Check if it's already been requested in [issues](https://github.com/vuetifyjs/0/issues)
- Explain the use case and why it would benefit others
- Consider if it fits the headless/composable philosophy of Vuetify0

## Local Development

### Prerequisites

- Node.js 20.19+ or 22+
- pnpm 10.6+
- Git

### Setup

```bash
# Clone the repository
git clone https://github.com/vuetifyjs/0.git
cd 0

# Install dependencies
pnpm install

# Start the playground
pnpm dev

# Start the docs site
pnpm dev:docs
```

### Project Structure

```text
├── packages/
│   └── 0/              # @vuetify/v0 - main package
│       ├── src/
│       │   ├── components/    # Vue components
│       │   ├── composables/   # Composable functions
│       │   ├── utilities/     # Helper functions
│       │   └── types/         # TypeScript types
├── apps/
│   ├── docs/           # Documentation site
│   └── storybook/      # Storybook stories
└── playground/         # Development playground
```

### Useful Commands

```bash
# Development
pnpm dev              # Start playground
pnpm dev:docs         # Start docs site

# Testing
pnpm test             # Run tests in watch mode
pnpm test:run         # Run tests once

# Type checking
pnpm typecheck        # Check all packages

# Linting
pnpm lint             # Lint codebase
pnpm lint:fix         # Auto-fix lint issues

# Building
pnpm build            # Build packages
```

## Pull Requests

### Before Submitting

1. Create a new branch from `master`
2. Make your changes
3. Run `pnpm lint:fix` to fix formatting
4. Run `pnpm typecheck` to check types
5. Run `pnpm test:run` to verify tests pass
6. Write tests for new functionality

### PR Guidelines

- Keep PRs focused - one feature or fix per PR
- Write a clear title and description
- Reference any related issues
- Be responsive to feedback

### Branch Naming

Use descriptive branch names:

- `fix/issue-description` - Bug fixes
- `feat/feature-name` - New features
- `docs/what-changed` - Documentation updates
- `refactor/what-changed` - Code refactoring

## Commit Messages

Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:

```text
type(scope): subject
```

### Types

- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation changes
- `refactor` - Code refactoring
- `test` - Adding or updating tests
- `chore` - Maintenance tasks

### Examples

```bash
feat(useSelection): add toggle method
fix(ExpansionPanel): correct aria-expanded state
docs(getting-started): update installation instructions
refactor(useRegistry): simplify reindex logic
test(useForm): add validation edge cases
```

### Guidelines

- Use imperative mood ("add" not "added")
- Keep the subject under 60 characters
- Don't end with a period
- Reference issues when applicable: `fix(useForm): validation error (#123)`

## Code Style

### General

- Use TypeScript for all new code
- Follow existing patterns in the codebase
- Prefer `function` declarations over `const` arrow functions
- Use single-word variable names when clear
- Add JSDoc comments for public APIs

### Composables

- Place in `packages/0/src/composables/`
- Each composable in its own directory with `index.ts`
- Include `@module` JSDoc block at the top
- Colocate tests as `index.test.ts`
- Export both standalone and context-creation functions

### Components

- Follow the compound component pattern (Root/Item)
- Extend `AtomProps` for polymorphic components
- Use `useProxyModel` for v-model binding
- Include proper ARIA attributes

## Testing

- Write tests for new composables and components
- Focus on behavior, not implementation details
- Test edge cases and error conditions
- Use `describe` blocks to organize related tests

```ts
describe('useSelection', () => {
  it('should select an item', () => {
    // ...
  })

  it('should respect mandatory option', () => {
    // ...
  })
})
```

## Questions?

- [Discord](https://community.vuetifyjs.com) - Real-time chat and questions
- [GitHub Issues](https://github.com/vuetifyjs/0/issues) - Bug reports and feature requests

Thank you for contributing!

---

# Frequently Asked
URL: https://0.vuetifyjs.com/introduction/frequently-asked

<script setup>
import FaqList from '@/components/docs/FaqList.vue'

const faqs = [
  {
    id: 'what-is',
    question: 'What is Vuetify0?',
    answer: 'Vuetify0 is a collection of headless UI primitives and composables for Vue 3. It provides unstyled, logic-focused components that handle accessibility, keyboard navigation, and state management while giving you complete control over styling.'
  },
  {
    id: 'difference',
    question: 'How is Vuetify0 different from Vuetify?',
    answer: 'Vuetify is a full-featured Material Design component framework with opinionated styling, theming, and a complete design system. Vuetify0 is headless - components have no built-in styles. You bring your own CSS using Tailwind, UnoCSS, or plain CSS. Think of Vuetify0 as the foundation layer that Vuetify and other component libraries could be built on top of.'
  },
  {
    id: 'need-vuetify',
    question: 'Do I need Vuetify to use Vuetify0?',
    answer: 'No. Vuetify0 is a standalone package with no dependency on Vuetify. You can use it in any Vue 3 project.'
  },
  {
    id: 'styling',
    question: 'What styling approach should I use?',
    answer: 'Vuetify0 is style-agnostic. Use Tailwind CSS, UnoCSS, plain CSS, or any CSS-in-JS solution. All documentation examples use Tailwind-compatible utility classes that work in both Tailwind and UnoCSS.'
  },
  {
    id: 'composables',
    question: 'Why use composables instead of components?',
    answer: 'Components are great for common UI patterns, but composables give you more flexibility. You can build custom components, combine behaviors, control the entire DOM structure, and import only the logic you need for smaller bundles.'
  },
  {
    id: 'accessibility',
    question: 'Is Vuetify0 accessible?',
    answer: 'Yes. Components include proper ARIA attributes, keyboard navigation, and focus management following WAI-ARIA patterns. The headless approach means you are responsible for visual styling, but the accessibility logic is built-in.'
  },
  {
    id: 'ssr',
    question: 'Does Vuetify0 support SSR?',
    answer: 'Yes. All composables and components are SSR-safe. Use the IN_BROWSER constant for browser-only code, and the useHydration composable for hydration-aware rendering.'
  },
  {
    id: 'browsers',
    question: 'What browsers are supported?',
    answer: 'Vuetify0 supports all modern browsers (Chrome, Firefox, Safari, Edge). There is no IE11 support. Some features like the Popover component use newer APIs that may have limited browser support.'
  },
  {
    id: 'nuxt',
    question: 'Can I use Vuetify0 with Nuxt?',
    answer: 'Yes. Install the package and import components/composables as needed. No special Nuxt module is required, though one may be provided in the future.'
  },
  {
    id: 'contribute',
    question: 'How do I contribute?',
    answer: 'See the <a href="/introduction/contributing">Contributing</a> page for guidelines. The project is open source at <a href="https://github.com/vuetifyjs/0">github.com/vuetifyjs/0</a>.'
  },
  {
    id: 'help',
    question: 'Where can I get help?',
    answer: '<a href="https://github.com/vuetifyjs/0/issues">GitHub Issues</a> for bug reports and feature requests, or the <a href="https://community.vuetifyjs.com">Vuetify Discord</a> community for real-time chat and questions.'
  }
]
</script>

# Frequently Asked

Common questions and answers about Vuetify0.

Have a question that isn't answered here? Join our [Discord community](https://community.vuetifyjs.com) or open an [issue on GitHub](https://github.com/vuetifyjs/0/issues).



---

# Getting Started
URL: https://0.vuetifyjs.com/introduction/getting-started

# Get started with Vuetify0

Vuetify0 provides headless UI primitives and composables for Vue 3. Components are unstyled and logic-focused, giving you complete control over styling while handling accessibility, keyboard navigation, and state management.

## Installation

Install `@vuetify/v0` with your preferred package manager:

::: code-group

```bash pnpm
pnpm add @vuetify/v0
```

```bash npm
npm install @vuetify/v0
```

```bash yarn
yarn add @vuetify/v0
```

```bash bun
bun add @vuetify/v0
```

:::

## Requirements

- Vue 3.3.0 or higher
- Node 22+

## Quick Start

Import and use components directly - no plugin installation required:

```vue QuickStart.vue playground
<script setup lang="ts">
  import { ExpansionPanel } from '@vuetify/v0'
  import { ref } from 'vue'

  const expanded = ref([])
</script>

<template>
  <ExpansionPanel.Root v-model="expanded" multiple>
    <ExpansionPanel.Item value="item-1">
      <ExpansionPanel.Activator>
        Section 1
      </ExpansionPanel.Activator>

      <ExpansionPanel.Content>
        Content for section 1
      </ExpansionPanel.Content>
    </ExpansionPanel.Item>
  </ExpansionPanel.Root>
</template>
```

Components are completely unstyled. Add your own classes using Tailwind, UnoCSS, or plain CSS.

## Styling

v0 is style-agnostic. Choose your preferred CSS framework and map theme colors to v0's CSS variables.

### UnoCSS

[UnoCSS](https://unocss.dev) is our recommended choice for its speed and flexibility.

#### 1. Install

::: code-group

```bash pnpm
pnpm add -D unocss @unocss/preset-wind
```

```bash npm
npm install -D unocss @unocss/preset-wind
```

```bash yarn
yarn add -D unocss @unocss/preset-wind
```

```bash bun
bun add -D unocss @unocss/preset-wind
```

:::

#### 2. Configure

```ts uno.config.ts
import { defineConfig, presetWind } from 'unocss'

export default defineConfig({
  presets: [presetWind()],
  theme: {
    colors: {
      primary: 'var(--v0-primary)',
      surface: 'var(--v0-surface)',
      'on-primary': 'var(--v0-on-primary)',
      'on-surface': 'var(--v0-on-surface)',
    },
  },
})
```

#### 3. Add Vite Plugin

```ts vite.config.ts
import UnoCSS from 'unocss/vite'

export default defineConfig({
  plugins: [
    vue(),
    UnoCSS(),
  ],
})
```

#### 4. Import Styles

```ts main.ts
import 'virtual:uno.css'
```

Now use utility classes in your components:

```vue
<template>
  <button class="bg-primary text-on-primary px-4 py-2 rounded">
    Click me
  </button>
</template>
```

### Tailwind CSS v4

[Tailwind v4](https://tailwindcss.com) uses CSS-first configuration with native cascade layers.

#### 1. Install

::: code-group

```bash pnpm
pnpm add -D tailwindcss @tailwindcss/vite
```

```bash npm
npm install -D tailwindcss @tailwindcss/vite
```

```bash yarn
yarn add -D tailwindcss @tailwindcss/vite
```

```bash bun
bun add -D tailwindcss @tailwindcss/vite
```

:::

#### 2. Add Vite Plugin

```ts vite.config.ts
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    vue(),
    tailwindcss(),
  ],
})
```

#### 3. Create Stylesheet

```css src/styles/main.css
@import "tailwindcss";

@theme {
  --color-primary: var(--v0-primary);
  --color-surface: var(--v0-surface);
  --color-on-primary: var(--v0-on-primary);
  --color-on-surface: var(--v0-on-surface);
}
```

#### 4. Import Styles

```ts main.ts
import './styles/main.css'
```

Now use utility classes in your components:

```vue
<template>
  <button class="bg-primary text-on-primary px-4 py-2 rounded">
    Click me
  </button>
</template>
```

### CSS Modules

Vue's built-in [CSS Modules](https://vuejs.org/api/sfc-css-features#css-modules) require zero configuration.

```vue Button.vue
<template>
  <button :class="$style.btn">
    Click me
  </button>
</template>

<style module>
  .btn {
    background: var(--v0-primary);
    color: var(--v0-on-primary);
    padding: 0.5rem 1rem;
    border-radius: 0.25rem;
  }
</style>
```

Type-safe access via `useCssModule()`:

```vue
<script setup lang="ts">
  import { useCssModule } from 'vue'

  const $style = useCssModule()
</script>

<template>
  <button :class="$style.btn">Click me</button>
</template>
```

> [!TIP]
> For dark mode, custom themes, and design tokens, see the [Theming Guide](/guide/theming).

## Nuxt 3

v0 works with Nuxt 3 via a standard plugin.

### 1. Create Plugin

```ts plugins/v0.ts
import { createHydrationPlugin, createThemePlugin } from '@vuetify/v0'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(createHydrationPlugin())
  nuxtApp.vueApp.use(
    createThemePlugin({
      default: 'light',
      themes: {
        light: {
          dark: false,
          colors: {
            primary: '#3b82f6',
            surface: '#ffffff',
            'on-primary': '#ffffff',
            'on-surface': '#212121',
          },
        },
        dark: {
          dark: true,
          colors: {
            primary: '#60a5fa',
            surface: '#1e1e1e',
            'on-primary': '#1a1a1a',
            'on-surface': '#e0e0e0',
          },
        },
      },
    }),
  )
})
```

### 2. Configure Nuxt

```ts nuxt.config.ts
export default defineNuxtConfig({
  build: {
    transpile: ['@vuetify/v0'],
  },
})
```

> [!TIP]
> For auto-imports, SSR hydration, and theme persistence, see the [Nuxt Guide](/guide/nuxt).

## Exposed Exports

The following export paths exist for the Vuetify0 framework:

| Name | Description |
| ---- | ----------- |
| `@vuetify/v0` | Main entry point exposing all components, composables, and utilities. |
| `@vuetify/v0/components` | Components only. |
| `@vuetify/v0/composables` | Composables only. |
| `@vuetify/v0/utilities` | Utilities only. |
| `@vuetify/v0/constants` | Constants only (not included in main entry). |

```ts
// Everything
import { ExpansionPanel, useSelection } from '@vuetify/v0'

// Components only
import { ExpansionPanel, Single, Group } from '@vuetify/v0/components'

// Composables only
import { useSelection, useTheme, useForm } from '@vuetify/v0/composables'

// Utilities only
import { isObject, isString } from '@vuetify/v0/utilities'

// Constants only
import { IN_BROWSER } from '@vuetify/v0/constants'
```

## Next Steps

- [Explore Components](/components/) See all available components
- [Browse Composables](/composables/) Dive into the composables API

---

# guide
URL: https://0.vuetifyjs.com/guide

# Guide

Learn v0's patterns and build headless UI systems. Start with [Getting Started](/introduction/getting-started) if you haven't installed v0 yet.

## Prerequisites

Before diving into the guides, ensure you're familiar with:

- **Required**: Vue 3 basics (ref, computed, provide/inject)
- **Helpful**: Composables pattern, TypeScript generics

## What's Different About v0

| Traditional Component Libraries | v0 Approach |
| - | - |
| Pre-styled, override with CSS | Zero styles - you own all styling |
| Props configure behavior | Composables expose reactive state |
| Component = black box | Component = transparent composition |
| Fight the framework | Build with the framework |

**The v0 Mental Model:**

- Components are **delivery mechanisms**, not behavior containers
- Logic lives in **composables** you can use independently
- **Trinity pattern**: `[use, provide, context]` - predictable, debuggable
- **Registry/Context pattern**: Parent-child coordination without prop drilling

## Learning Paths

### Track A: Core Concepts

For understanding the system architecture.

| Guide | What You'll Learn |
| - | - |
| [Structure](/guide/structure) | Package organization, imports, file conventions |
| [Core](/guide/core) | Trinity, Context, Registry patterns |
| [Components](/guide/components) | Component categories, Atom primitive, slot props |
| [Plugins](/guide/plugins) | Using and creating Vue plugins |

### Track B: Features & Polish

For building production UIs.

| Guide | What You'll Learn |
| - | - |
| [Theming](/guide/theming) | CSS variables, design tokens, dark mode |
| [Accessibility](/guide/accessibility) | ARIA patterns, keyboard nav, testing |
| [Utilities](/guide/utilities) | Helper functions, type guards |

> [!TIP]
> New to v0? Start with Track A. Already building? Jump to Track B as needed.

> [!SUGGESTION] How do I migrate an existing styled component library to use v0's headless approach?

## Quick Reference

| Pattern | Use Case | Guide |
| - | - | - |
| `createContext` | Share state across component tree | [Core](/guide/core) |
| `useSelection` | Multi-select, toggles, radio groups | [Composables](/composables/selection/use-selection) |
| `useRegistry` | Dynamic child registration | [Core](/guide/core) |
| `Atom` component | Polymorphic base element | [Components](/guide/components) |
| `useTheme` | Theme switching, CSS variables | [Theming](/guide/theming) |

---

# Accessibility
URL: https://0.vuetifyjs.com/guide/accessibility

# Accessibility

v0 provides ARIA attributes out-of-the-box through the `attrs` pattern. You provide styling and visual feedback.

## The `attrs` Pattern

Every v0 component exposes an `attrs` object containing all accessibility attributes. Spread it onto your elements:

```vue playground
<script setup>
  import { Selection } from '@vuetify/v0'

  const items = ['Apple', 'Banana', 'Cherry']
</script>

<template>
  <Selection.Root v-slot="{ attrs }">
    <div v-bind="attrs">
      <Selection.Item v-for="item in items" :key="item" v-slot="{ attrs }">
        <button v-bind="attrs">{{ item }}</button>
      </Selection.Item>
    </div>
  </Selection.Root>
</template>
```

### What's Included in `attrs`

| Component | ARIA Attributes Provided |
| - | - |
| Selection.Item | `aria-selected`, `aria-disabled`, `data-selected`, `data-disabled` |
| Group.Item | `role="checkbox"`, `aria-checked`, `aria-disabled`, `data-selected`, `data-disabled`, `data-mixed` |
| ExpansionPanel.Activator | `id`, `role`, `tabindex`, `aria-expanded`, `aria-controls`, `aria-disabled` |
| Pagination.Root | `aria-label`, `role="navigation"` (when not using `<nav>`) |
| Popover.Anchor | `popovertarget`, `data-popover-open` (uses native popover API) |

> [!TIP]
> Always spread the `attrs` object from slot props onto your interactive elements. Missing ARIA attributes break screen reader support.

## Developer Responsibilities

v0 provides the ARIA plumbing. You must provide:

| Responsibility | Example |
| - | - |
| Visual focus indicators | `:focus-visible { outline: 2px solid blue }` |
| Color contrast | Ensure 4.5:1 ratio minimum |
| Visible labels | Add `<label>` or `aria-label` for inputs |
| Skip links | Navigation landmarks for keyboard users |

### Focus Trapping

v0 does **not** provide focus trapping. Use external solutions:

- [focus-trap](https://github.com/focus-trap/focus-trap)
- Native `inert` attribute for siblings
- [vue-final-modal](https://vue-final-modal.org/)

### Roving Tabindex

v0 does **not** provide roving tabindex. This keeps the library headless - implement in your design system layer if needed for arrow key navigation between items.

## Keyboard Navigation

### What v0 Handles

- `tabindex` management (-1 when disabled, 0 when enabled)
- ARIA state synchronization (`aria-expanded`, `aria-selected`)
- Data attributes for styling (`data-selected`, `data-disabled`)

### What You Implement

| Pattern | Keys to Handle |
| - | - |
| List selection | Arrow keys, Home/End |
| Menus | Arrow keys, Escape, Enter |
| Dialogs | Escape to close, focus trap |
| Tabs | Arrow keys, Home/End |

```ts
// You implement navigation logic - v0 provides selection state
function onKeydown (e: KeyboardEvent, ids: string[], currentIndex: number) {
  switch (e.key) {
    case 'ArrowDown': selection.select(ids[currentIndex + 1]); break
    case 'ArrowUp': selection.select(ids[currentIndex - 1]); break
    case 'Home': selection.select(ids[0]); break
    case 'End': selection.select(ids[ids.length - 1]); break
  }
}
```

## Testing Strategies

### Automated Testing

```ts MyComponent.test.ts
import { axe } from 'vitest-axe'

it('passes accessibility audit', async () => {
  const { container } = render(MyComponent)
  expect(await axe(container)).toHaveNoViolations()
})
```

### Manual Testing Checklist

- [ ] Tab through all interactive elements
- [ ] Verify focus visibility
- [ ] Test with keyboard only (no mouse)
- [ ] Check color contrast with DevTools
- [ ] Validate with browser accessibility tree

### Recommended Tools

| Tool | Purpose |
| - | - |
| axe DevTools | Browser extension for WCAG scanning |
| Lighthouse | Built-in Chrome audit |
| NVDA/VoiceOver | Screen reader verification |

## Internationalization

v0's `useLocale` handles RTL and translated labels. See [useLocale](/composables/plugins/use-locale) for accessibility label translations.

> [!SUGGESTION] How do I implement arrow key navigation for a custom list component?

> [!SUGGESTION] How do I integrate accessibility testing into my CI/CD pipeline?

---

# Ai Tools
URL: https://0.vuetifyjs.com/guide/ai-tools

# AI Tools

v0 provides machine-readable documentation files following the [llms.txt](https://llmstxt.org/) standard. These files help AI assistants understand the library without hallucinating APIs or patterns.

## Available Files

| File | Size | Purpose | Best For |
| - | - | - | - |
| <a href="/llms.txt" target="_blank" class="v0-link">llms.txt↗</a> | ~6 KB | Curated index with links | Quick context, navigation |
| <a href="/llms-full.txt" target="_blank" class="v0-link" style="white-space: nowrap">llms-full.txt↗</a> | ~220 KB | Complete documentation | Deep understanding, code generation |

> [!SUGGESTION] When should I use llms.txt vs llms-full.txt?

## Usage Examples

### ChatGPT / Claude.ai

Paste the URL directly in chat:

```txt
Read https://0.vuetifyjs.com/llms-full.txt and help me build a multi-select dropdown using v0 composables.
```

### Cursor / Windsurf

Add to your project's `.cursorrules` or AI context:

```txt
@https://0.vuetifyjs.com/llms.txt
```

### Claude Code

Fetch the documentation in your session:

```txt
WebFetch https://0.vuetifyjs.com/llms-full.txt
```

> [!TIP]
> For the best experience with Claude, use [Vuetify MCP](/guide/vuetify-mcp) instead. It provides structured API access rather than raw text.

## What's Included

**llms.txt** contains categorized links to:

- 10 guide pages (introduction, theming, accessibility, etc.)
- 9 headless components (Atom, Avatar, Pagination, etc.)
- 34 composables across 7 categories
- FAQ and contributing guides

**llms-full.txt** includes the complete content of every documentation page, stripped of Vue components and frontmatter for cleaner LLM consumption.

## How It Works

- `llms.txt` is manually curated in `apps/docs/public/`
- `llms-full.txt` is auto-generated at build time from all markdown pages
- Both are served statically and cached for performance

---

# Components
URL: https://0.vuetifyjs.com/guide/components

# Components

v0 components are Vue wrappers around composables. Composables hold logic, components provide Vue integration via slots, props, and emits.

## Component Philosophy

- **Headless**: Zero styling - you own all CSS
- **Slot-driven**: All customization through scoped slots
- **Accessible**: ARIA attributes via `attrs` object
- **Composable-backed**: Use components or composables directly

> [!TIP]
> Always spread the `attrs` object onto your elements. It contains ARIA attributes and data attributes for accessibility and styling.

> [!SUGGESTION] How do I add styling or CSS classes to headless components?

## Component Categories

| Category | Purpose | Examples |
| - | - | - |
| **Primitives** | Base building blocks | [Atom](/components/primitives/atom) |
| **Providers** | Pure state management, no DOM | [Selection](/components/providers/selection), [Single](/components/providers/single), [Group](/components/providers/group), [Step](/components/providers/step) |
| **Semantic** | Meaningful HTML defaults | [Avatar](/components/semantic/avatar), [Pagination](/components/semantic/pagination) |
| **Disclosure** | Show/hide patterns | [ExpansionPanel](/components/disclosure/expansion-panel), [Popover](/components/disclosure/popover) |

## Atom: The Foundation

The `Atom` component is a polymorphic base element supporting any HTML tag:

```vue
<script lang="ts" setup>
  function onClick() {
    console.log('clicked')
  }
</script>

<template>
  <!-- Render as button -->
  

  <!-- Render as link -->
  

  <!-- Renderless mode - slot only -->
  
</template>
```

### Rendering Modes

| Mode | Usage | Output |
| - | - | - |
| Element | `as="button"` | `<button>` with slot content |
| Renderless | `:as="null"` or `renderless` | Slot only, no wrapper |

## Slot Props Pattern

Every component exposes `attrs` in its default slot. Spread onto your element for behavior and accessibility:

```vue playground
<script setup lang="ts">
  import { Selection } from '@vuetify/v0'

  const items = ['Apple', 'Banana', 'Cherry']
</script>

<template>
  <Selection.Root>
    <Selection.Item v-for="item in items" v-slot="{ attrs, isSelected, toggle }">
      <button
        v-bind="attrs"
        :class="{ 'bg-primary': isSelected }"
        @click="toggle"
      >
        {{ item }}
      </button>
    </Selection.Item>
  </Selection.Root>
</template>
```

### Common Slot Props

| Component Type | Slot Props |
| - | - |
| Selection.Item | `attrs`, `isSelected`, `toggle`, `select`, `unselect` |
| Group.Item | `attrs`, `isSelected`, `isMixed`, `toggle` |
| ExpansionPanel.Activator | `attrs`, `isSelected`, `toggle` |
| Popover.Root | `id`, `isSelected`, `toggle` |
| Popover.Anchor | `attrs`, `isOpen` |
| Popover.Content | `attrs`, `isOpen` |

### Data Attributes

Components emit data attributes for CSS styling:

```css
[data-selected] { background: var(--primary); }
[data-disabled] { opacity: 0.5; }
[data-mixed] { /* tri-state checkbox */ }
[data-popover-open] { /* popover is visible */ }
```

## Component Reference

### Primitives

- [Atom](/components/primitives/atom) Polymorphic base element

### Providers

- [Selection](/components/providers/selection) Multi-selection state
- [Single](/components/providers/single) Single-selection state
- [Group](/components/providers/group) Multi-select with tri-state
- [Step](/components/providers/step) Sequential navigation

### Semantic

- [Avatar](/components/semantic/avatar) Image with fallback
- [Pagination](/components/semantic/pagination) Page navigation

### Disclosure

- [ExpansionPanel](/components/disclosure/expansion-panel) Accordion pattern
- [Popover](/components/disclosure/popover) Floating content

---

# Composables
URL: https://0.vuetifyjs.com/guide/composables

# Composables

Composables are the foundation of v0. They provide headless logic that you can use directly or through wrapper components.

## Composables vs Components

Both approaches use the same underlying logic:

```ts
// Direct composable usage
const selection = createSelection({ multiple: true })
selection.register({ id: 'a', value: 'Apple' })
selection.select('a')
```

```vue playground
<template>
  <Selection.Root v-model="selected" multiple>
    <Selection.Item value="Apple">Apple</Selection.Item>
  </Selection.Root>
</template>
```

### When to Use Each

| Use Composables When | Use Components When |
| - | - |
| Need full control over rendering | Want declarative templates |
| Building custom abstractions | Standard UI patterns |
| Non-DOM contexts (stores, workers) | Accessibility attrs needed |
| Maximum flexibility | Faster development |

> [!TIP]
> Components and composables are interchangeable. Every component uses a composable internally—you can always drop to the composable for more control.

> [!SUGGESTION] How do I choose between composables and components for my use case?

## Categories

### Foundation

Factories that create other composables:

| Composable | Purpose |
| - | - |
| [createContext](/composables/foundation/create-context) | Type-safe provide/inject |
| [createTrinity](/composables/foundation/create-trinity) | `[use, provide, context]` tuple |
| [createPlugin](/composables/foundation/create-plugin) | Vue plugin factory |

### Registration

Collection management primitives:

| Composable | Purpose |
| - | - |
| [useRegistry](/composables/registration/use-registry) | Base collection with lookup |
| [useTokens](/composables/registration/use-tokens) | Design token aliases |
| [useQueue](/composables/registration/use-queue) | Time-based queue |
| [useTimeline](/composables/registration/use-timeline) | Undo/redo history |

### Selection

State management for selection patterns:

| Composable | Purpose |
| - | - |
| [useSelection](/composables/selection/use-selection) | Multi-select base |
| [useSingle](/composables/selection/use-single) | Radio, tabs, accordion |
| [useGroup](/composables/selection/use-group) | Checkboxes, tri-state |
| [useStep](/composables/selection/use-step) | Wizard, stepper, carousel |

### Forms

Form state and validation:

| Composable | Purpose |
| - | - |
| [useForm](/composables/forms/use-form) | Validation, dirty tracking |
| [useProxyModel](/composables/forms/use-proxy-model) | v-model bridge |

### Plugins

App-level features installed via `app.use()`:

| Composable | Purpose |
| - | - |
| [useTheme](/composables/plugins/use-theme) | Dark/light mode |
| [useLocale](/composables/plugins/use-locale) | i18n, RTL |
| [useBreakpoints](/composables/plugins/use-breakpoints) | Responsive queries |
| [useStorage](/composables/plugins/use-storage) | Persistent state |

### Utilities

Standalone helpers:

| Composable | Purpose |
| - | - |
| [useFilter](/composables/utilities/use-filter) | Array filtering |
| [usePagination](/composables/utilities/use-pagination) | Page navigation |
| [useVirtual](/composables/utilities/use-virtual) | Virtual scrolling |

## Usage Patterns

### Direct Factory Call

For standalone instances:

```ts
import { createSelection } from '@vuetify/v0'

const tabs = createSelection({ multiple: false })
tabs.register({ id: 'home', value: 'Home' })
tabs.register({ id: 'about', value: 'About' })
tabs.select('home')
```

### Context Injection

For component tree sharing:

```ts
// Parent
import { createSelectionContext } from '@vuetify/v0'

const [useTabSelection, provideTabSelection] = createSelectionContext({
  namespace: 'tabs',
  multiple: false,
})
provideTabSelection()

// Child
const selection = useTabSelection()
selection.select('home')
```

### Plugin Installation

For app-wide singletons:

```ts main.ts
import { createApp } from 'vue'
import { createThemePlugin } from '@vuetify/v0'

const app = createApp(App)
app.use(
  createThemePlugin({
    default: 'light',
    themes: { light: {...}, dark: {...} },
  }),
)
```

## Composing Composables

Build complex behavior by combining primitives:

```ts composables/useDataTable.ts
import { createSelection, createFilter, createPagination } from '@vuetify/v0'

// Filterable, paginated selection
const items = ref([...])
const query = ref('')

const filter = createFilter()
const { items: filtered } = filter.apply(query, items)

const pagination = createPagination({
  size: () => filtered.value.length,
  itemsPerPage: 10,
})
const selection = createSelection({ multiple: true })

// Visible items with selection state
const visibleItems = computed(() => {
  const start = pagination.pageStart.value
  const end = pagination.pageStop.value
  return filtered.value.slice(start, end)
})
```

## TypeScript

All composables are fully typed. The value type is inferred from registration:

```ts
interface MyItem {
  id: string
  label: string
}

const selection = createSelection()
selection.register({ id: '1', value: { id: '1', label: 'First' } as MyItem })

// Type-safe access via ticket
const ticket = selection.get('1')
ticket?.value // MyItem
```

> [!SUGGESTION] Which composables should I use for a data table with filtering and pagination?

---

# Core
URL: https://0.vuetifyjs.com/guide/core

# Core

v0's core architecture provides type-safe dependency injection and composable patterns. This page explains **how v0 works**. For creating plugins, see [Plugins Guide](/guide/plugins).

## Architecture Overview

```mermaid
flowchart TD
    A[createContext] --> B[createTrinity]
    B --> C[createPlugin]

    A -.- A1["Type-safe provide/inject wrapper"]
    B -.- B1["[use, provide, context] tuple"]
    C -.- C1["Vue plugin factory"]
```

## The Trinity Pattern

The signature pattern of v0. Every composable returns a readonly 3-tuple:

```ts
const [useTheme, provideTheme, theme] = createThemeContext()

// 1. useTheme - Inject from ancestor
const theme = useTheme()

// 2. provideTheme - Provide to descendants
provideTheme()              // Use defaults
provideTheme(customTheme)   // Provide custom

// 3. theme - Direct access without DI
theme.cycle()  // Cycle through themes
```

### Why Three Elements?

| Element | Purpose |
| - | - |
| `useContext` | Consume in child components |
| `provideContext` | Provide from parent (defaults to built-in context) |
| `defaultContext` | Standalone access, testing, outside Vue |

> [!TIP]
> The third element (`defaultContext`) is useful for unit testing without mounting Vue components.

## createContext

Type-safe wrapper around Vue's provide/inject that **throws on missing context** (no silent undefined):

### Static Key Mode

```ts
const [useTheme, provideTheme] = createContext<ThemeContext>('v0:theme')

// Provider
provideTheme({ isDark: ref(false), toggle: () => {} })

// Consumer - throws if not provided
const theme = useTheme()
```

### Dynamic Key Mode

For nested contexts (panels within panels):

```ts
const [usePanel, providePanel] = createContext<PanelContext>()

// Provider with runtime key
providePanel('panel-1', context)

// Consumer with same key
const panel = usePanel('panel-1')
```

### Suffix Pattern

For parent-child context hierarchies:

```ts
const [useItem, provideItem] = createContext<ItemContext>({ suffix: 'item' })

provideItem('v0:panel', context)  // Provides to 'v0:panel:item'
useItem('v0:panel')               // Injects from 'v0:panel:item'
```

## Registry System

`useRegistry` is the foundational data structure. All selection, forms, and token composables extend it.

```ts
const registry = useRegistry()

// Register items
const ticket = registry.register({ id: 'item-1', value: 'First' })

// Lookup
registry.get('item-1')      // Get by ID
registry.browse('First')    // Get IDs by value
registry.lookup(0)          // Get ID by index

// Cleanup
registry.unregister('item-1')
```

### Ticket Structure

Every registered item is a "ticket":

```ts
interface RegistryTicket {
  id: ID,              // Unique identifier
  index: number,       // Position in registry
  value: unknown,      // Associated data
  valueIsIndex: boolean, // True if value wasn't explicitly set
}
```

### Extension Chain

```mermaid
flowchart LR
    R[useRegistry] --> S[useSelection]
    R --> T[useTokens]
    R --> F[useForm]
    S --> Si[useSingle]
    S --> G[useGroup]
    Si --> St[useStep]
```

| Composable | Extends | Adds |
| - | - | - |
| `useRegistry` | — | Base collection management |
| `useSelection` | Registry | `selectedIds` Set |
| `useSingle` | Selection | Single selection constraint |
| `useGroup` | Selection | Tri-state, batch ops |
| `useStep` | Single | Navigation (next/prev/first/last) |
| `useTokens` | Registry | Alias resolution |
| `useForm` | Registry | Validation |

## Selection System

### useSelection

Base multi-selection with Set-based tracking:

```ts
const selection = createSelection({ multiple: true })

selection.register({ id: 'a', value: 'Apple' })
selection.register({ id: 'b', value: 'Banana' })

selection.select('a')
selection.selectedIds  // Set { 'a' }
```

### useSingle

Auto-clears previous selection:

```ts
const tabs = createSingle({ mandatory: true })

tabs.onboard([
  { id: 'tab-1', value: 'Home' },
  { id: 'tab-2', value: 'About' },
])

tabs.select('tab-1')
tabs.select('tab-2')  // tab-1 auto-unselected
tabs.selectedId.value // 'tab-2'
```

### useGroup

Multi-select with tri-state:

```ts
const checkboxes = createGroup()

checkboxes.onboard([
  { id: 'a', value: 'Option A' },
  { id: 'b', value: 'Option B' },
  { id: 'c', value: 'Option C' },
])

checkboxes.select(['a', 'b'])
checkboxes.selectAll()
checkboxes.isMixed.value  // true when some (not all) selected
```

### useStep

Sequential navigation:

```ts
const wizard = createStep({ circular: false })

wizard.onboard([
  { id: 'step-1', value: 'Step 1' },
  { id: 'step-2', value: 'Step 2' },
  { id: 'step-3', value: 'Step 3' },
])

wizard.first()  // Select first step
wizard.next()   // Move forward
wizard.prev()   // Move backward
wizard.last()   // Jump to end
```

## Best Practices

### Naming Conventions

| Prefix | Purpose | Example |
| - | - | - |
| `use*` | Inject from context | `useTheme()` |
| `create*` | Factory returning instance | `createSelection()` |
| `create*Context` | Factory returning trinity | `createThemeContext()` |
| `create*Plugin` | Factory returning Vue plugin | `createThemePlugin()` |

### When to Use Each

| Need | Use |
| - | - |
| Share state in component tree | `provideContext` / `useContext` |
| App-wide singleton | `createPlugin` with `app.use()` |
| Standalone logic | Direct factory call |
| Testing | Trinity's third element |

> [!SUGGESTION] How do I handle scoped contexts for nested components without prop drilling?

---

# Features
URL: https://0.vuetifyjs.com/guide/features

# Features

Review and select from a variety of features to enhance your UI library



---

# Nuxt
URL: https://0.vuetifyjs.com/guide/nuxt

# Nuxt 3

v0 integrates with Nuxt 3 through standard Vue plugin registration. This guide covers SSR considerations, auto-imports, and theme persistence.

## Basic Setup

See [Getting Started](/introduction/getting-started#nuxt-3) for the minimal plugin setup.

## Auto-Imports

Configure Nuxt to auto-import v0 composables:

```ts nuxt.config.ts
export default defineNuxtConfig({
  build: {
    transpile: ['@vuetify/v0'],
  },
  imports: {
    imports: [
      { from: '@vuetify/v0', name: 'useTheme' },
      { from: '@vuetify/v0', name: 'useSelection' },
      { from: '@vuetify/v0', name: 'useGroup' },
      { from: '@vuetify/v0', name: 'useSingle' },
      { from: '@vuetify/v0', name: 'useStep' },
      { from: '@vuetify/v0', name: 'usePagination' },
      { from: '@vuetify/v0', name: 'useForm' },
      { from: '@vuetify/v0', name: 'useHydration' },
      { from: '@vuetify/v0', name: 'useBreakpoints' },
      { from: '@vuetify/v0', name: 'IN_BROWSER' },
    ],
  },
})
```

## SSR Considerations

### The `IN_BROWSER` Constant

Guard browser-only code with `IN_BROWSER`:

```ts
import { IN_BROWSER } from '@vuetify/v0'

if (IN_BROWSER) {
  localStorage.setItem('key', 'value')
  window.addEventListener('resize', handler)
}
```

### Hydration State

Use `useHydration` to defer browser-only rendering:

```vue
<script lang="ts" setup>
  import { useHydration } from '@vuetify/v0'

  const { isHydrated } = useHydration()
</script>

<template>
  <div v-if="isHydrated">
    
  </div>
</template>
```

The hydration plugin:
- Sets `isHydrated` to `false` during SSR
- Flips to `true` after the root component mounts on client
- Falls back gracefully if not installed

### Theme SSR Integration

The theme plugin automatically integrates with Nuxt's `@unhead/vue` to inject styles during SSR. No additional configuration required.

## Theme Persistence

> [!TIP]
> Use cookies instead of localStorage for theme persistence. Cookies are available on the server, preventing flash of wrong theme.

For theme preference to persist across SSR requests, use cookies instead of localStorage:

```ts plugins/v0.ts
import { createHydrationPlugin, createThemePlugin, IN_BROWSER } from '@vuetify/v0'

export default defineNuxtPlugin((nuxtApp) => {
  const themeCookie = useCookie<'light' | 'dark'>('theme', {
    default: () => 'light',
  })

  function resolveTheme(): 'light' | 'dark' {
    if (themeCookie.value) return themeCookie.value
    if (!IN_BROWSER) return 'light'
    return window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark'
      : 'light'
  }

  nuxtApp.vueApp.use(createHydrationPlugin())
  nuxtApp.vueApp.use(
    createThemePlugin({
      default: resolveTheme(),
      themes: {
        light: {
          dark: false,
          colors: {
            primary: '#3b82f6',
            surface: '#ffffff',
            'on-primary': '#ffffff',
            'on-surface': '#212121',
          },
        },
        dark: {
          dark: true,
          colors: {
            primary: '#60a5fa',
            surface: '#1e1e1e',
            'on-primary': '#1a1a1a',
            'on-surface': '#e0e0e0',
          },
        },
      },
    }),
  )
})
```

To sync theme changes back to the cookie:

```vue
<script setup lang="ts">
  import { useTheme } from '@vuetify/v0'
  import { watch } from 'vue'

  const theme = useTheme()
  const themeCookie = useCookie('theme')

  watch(() => theme.selectedId.value, (id) => {
    themeCookie.value = id
  })
</script>
```

## SSR Compatibility Reference

| Feature | SSR Support | Notes |
| - | - | - |
| Components | Full | All compound components work in SSR |
| `useTheme` | Full | Auto-injects styles via Nuxt head manager |
| `useHydration` | Full | Designed for SSR/client state sync |
| `useBreakpoints` | Partial | Returns defaults on server, measures on client |
| `useStorage` | Partial | Uses memory adapter on server |
| `usePagination` | Full | Width-based calculation defers to client |
| Observer composables | Partial | No-op on server, activate on client |

## Common Patterns

### Client-Only Components

For components that can't render on the server:

```vue
<template>
  
</template>
```

### Avoiding Hydration Mismatch

Common causes:
- Timestamps or random values during render
- Conditional rendering based on browser state
- Dynamic IDs without SSR-safe generation

```vue
<script setup lang="ts">
  import { useHydration } from '@vuetify/v0'

  const { isHydrated } = useHydration()

  // Bad: causes mismatch
  const time = new Date().toLocaleTimeString()

  // Good: defer to client
  const time = computed(() => isHydrated.value ? new Date().toLocaleTimeString() : '')
</script>
```

> [!SUGGESTION] How do I debug hydration mismatches in my Nuxt components?

> [!SUGGESTION] When should I use useHydration vs ClientOnly components?

---

# Plugins
URL: https://0.vuetifyjs.com/guide/plugins

# Plugins

v0 plugins are Vue plugins built with `createPlugin`. They provide app-wide singletons for features like theming, locale, and logging. For understanding the underlying architecture, see [Core](/guide/core).

## Using Built-in Plugins

### Basic Installation

```ts main.ts
import { createApp } from 'vue'
import { createThemePlugin, createLocalePlugin } from '@vuetify/v0'

const app = createApp(App)

// Install plugins
app.use(createThemePlugin())
app.use(createLocalePlugin())

app.mount('#app')
```

### With Options

```ts
app.use(
  createThemePlugin({
    default: 'dark',
    themes: {
      light: { dark: false, colors: { primary: '#1976D2' } },
      dark: { dark: true, colors: { primary: '#2196F3' } },
    },
  }),
)

app.use(
  createLocalePlugin({
    default: 'en',
    messages: { en: { hello: 'Hello' } },
  }),
)
```

## Available Plugins

| Plugin | Purpose | Composable |
| - | - | - |
| `createThemePlugin` | CSS variable theming, dark mode | [useTheme](/composables/plugins/use-theme) |
| `createLocalePlugin` | i18n, RTL support | [useLocale](/composables/plugins/use-locale) |
| `createLoggerPlugin` | Structured logging | [useLogger](/composables/plugins/use-logger) |
| `createStoragePlugin` | Reactive localStorage/sessionStorage | [useStorage](/composables/plugins/use-storage) |
| `createPermissionsPlugin` | Role-based access control | [usePermissions](/composables/plugins/use-permissions) |
| `createBreakpointsPlugin` | Responsive breakpoint detection | [useBreakpoints](/composables/plugins/use-breakpoints) |
| `createHydrationPlugin` | SSR hydration management | [useHydration](/composables/plugins/use-hydration) |

> [!TIP]
> All plugins are optional. Only install what you need—v0 works without any plugins installed.

> [!SUGGESTION] Which built-in plugins do I actually need? Can I use v0 without them?

## Creating Custom Plugins

### Basic Plugin

```ts plugins/analytics.ts
import { createContext, createPlugin } from '@vuetify/v0'

interface AnalyticsContext {
  track: (event: string, data?: Record<string, unknown>) => void
  identify: (userId: string) => void
}

// 1. Create the context for DI
const [useAnalytics, provideAnalytics] = createContext<AnalyticsContext>('my:analytics')

// 2. Create the plugin factory
export function createAnalyticsPlugin() {
  const context: AnalyticsContext = {
    track: (event, data) => console.log('Track:', event, data),
    identify: (userId) => console.log('Identify:', userId),
  }

  return createPlugin({
    namespace: 'my:analytics',
    provide: (app) => provideAnalytics(context, app),
  })
}

export { useAnalytics }
```

### Plugin with Options

```ts plugins/analytics.ts
interface AnalyticsOptions {
  apiKey: string
  debug?: boolean
}

export function createAnalyticsPlugin(options: AnalyticsOptions) {
  const { apiKey, debug = false } = options

  const context: AnalyticsContext = {
    track: (event, data) => {
      if (debug) console.log('Track:', event, data)
      // Send to analytics service
    },
    identify: (userId) => {
      // Identify user
    },
  }

  return createPlugin({
    namespace: 'my:analytics',
    provide: (app) => provideAnalytics(context, app),
  })
}

// Usage
app.use(createAnalyticsPlugin({ apiKey: 'xxx', debug: true }))
```

### Plugin with Adapter Pattern

For extensible plugins that support multiple backends:

```ts plugins/logger.ts
interface LoggerAdapter {
  log: (level: string, message: string) => void
}

interface LoggerContext {
  info: (msg: string) => void
  warn: (msg: string) => void
  error: (msg: string) => void
}

interface LoggerOptions {
  adapter?: LoggerAdapter
}

const consoleAdapter: LoggerAdapter = {
  log: (level, message) => console[level](message),
}

const [useLogger, provideLogger] = createContext<LoggerContext>('my:logger')

export function createLoggerPlugin(options: LoggerOptions = {}) {
  const adapter = options.adapter ?? consoleAdapter

  const context: LoggerContext = {
    info: (msg) => adapter.log('info', msg),
    warn: (msg) => adapter.log('warn', msg),
    error: (msg) => adapter.log('error', msg),
  }

  return createPlugin({
    namespace: 'my:logger',
    provide: (app) => provideLogger(context, app),
  })
}

// Custom adapter example
const sentryAdapter: LoggerAdapter = {
  log: (level, message) => {
    if (level === 'error') Sentry.captureMessage(message)
  },
}

app.use(createLoggerPlugin({ adapter: sentryAdapter }))
```

## Consuming Plugins

```vue
<script setup>
  import { useTheme, useLocale } from '@vuetify/v0'

  const theme = useTheme()
  const locale = useLocale()

  // Theme API
  theme.cycle()              // Cycle through themes
  theme.select('dark')       // Select specific theme
  theme.selectedItem.value   // Current theme ticket
  theme.selectedId.value     // 'light' | 'dark'
  theme.isDark.value         // boolean

  // Locale API
  locale.t('hello')
  locale.selectedItem.value  // Current locale ticket
  locale.selectedId.value    // 'en'
</script>
```

## Plugin vs Context

| Need | Use |
| - | - |
| App-wide singleton (one instance) | Plugin with `app.use()` |
| Multiple instances per subtree | Context with `provideContext` |
| Configurable at install time | Plugin |
| Configurable per component tree | Context |

## Best Practices

### 1. Provide Default Adapters

```ts
// Always provide a sensible default
const defaultAdapter = { /* ... */ }
const adapter = options.adapter ?? defaultAdapter
```

### 2. Type the Context Interface

```ts
// Define what consumers get
interface ThemeContext {
  selectedId: ComputedRef<string>
  select: (id: string) => void
  cycle: () => void
}
```

### 3. Handle Missing Installation

```ts
const theme = useTheme()
// useTheme throws if createThemePlugin isn't installed
// This is intentional - fail fast
```

---

# Structure
URL: https://0.vuetifyjs.com/guide/structure

# Structure

Quick reference for v0's codebase organization. Use this when navigating the source or deciding where to add new features.

## Package Layout

```txt
@vuetify/v0 (packages/0/src/)
├── components/       # Vue component wrappers (one folder per component)
├── composables/      # Core logic (flat structure, one folder per composable)
│   ├── createContext/
│   ├── useRegistry/
│   ├── useSelection/
│   └── ...           # All composables at same level
├── constants/        # Shared constants (IN_BROWSER, etc.)
├── types/            # Shared TypeScript types
├── utilities/        # Helper functions
└── index.ts          # Public exports
```

> [!TIP]
> Composables use a flat directory structure. The categories below are logical groupings for documentation purposes only.

## Composable Categories

| Category | Purpose | Key Exports |
| - | - | - |
| **foundation** | Core factories | `createContext`, `createTrinity`, `createPlugin` |
| **registration** | Collection management | `useRegistry`, `useTokens`, `useQueue`, `useTimeline`, `useProxyRegistry` |
| **selection** | Selection state | `useSelection`, `useSingle`, `useGroup`, `useStep` |
| **forms** | Form handling | `useForm`, `useProxyModel` |
| **system** | Browser APIs | `useEventListener`, `useKeydown`, `useResizeObserver`, `useClickOutside`, `useIntersectionObserver`, `useMutationObserver`, `useToggleScope` |
| **plugins** | App features | `useTheme`, `useLocale`, `useLogger`, `useStorage`, `useBreakpoints`, `useFeatures`, `useHydration`, `usePermissions` |
| **utilities** | UI helpers | `useFilter`, `usePagination`, `useVirtual`, `useOverflow` |
| **transformers** | Value transforms | `toArray`, `toReactive` |

## Component Categories

| Category | Purpose | Components |
| - | - | - |
| **primitives** | Base building blocks | `Atom` |
| **providers** | Pure state, no DOM | `Selection`, `Single`, `Group`, `Step` |
| **semantic** | Meaningful HTML | `Avatar`, `Pagination` |
| **disclosure** | Show/hide patterns | `ExpansionPanel`, `Popover` |

## Import Patterns

### Named Imports

```ts
import { useSelection, createThemePlugin, Atom } from '@vuetify/v0'
```

### Compound Components

```ts
import { Selection, ExpansionPanel } from '@vuetify/v0'

// Usage: Selection.Root, Selection.Item
// Usage: ExpansionPanel.Root, ExpansionPanel.Item, ExpansionPanel.Header,
//        ExpansionPanel.Activator, ExpansionPanel.Content
```

## File Conventions

### Composables

```txt
composables/
└── useSelection/
    ├── index.ts              # Main composable
    └── index.test.ts         # Colocated tests
```

### Components

```txt
components/
└── Selection/
    ├── SelectionRoot.vue     # Container component
    ├── SelectionItem.vue     # Child component
    ├── index.ts              # Compound export + re-exports
    └── index.test.ts         # Colocated tests
```

## Naming Conventions

| Prefix | Purpose | Example |
| - | - | - |
| `use*` | Composable (inject from context) | `useTheme()` |
| `create*` | Factory returning instance | `createSelection()` |
| `create*Context` | Factory returning trinity | `createThemeContext()` |
| `create*Plugin` | Factory returning Vue plugin | `createThemePlugin()` |
| `to*` | Value transformer | `toArray()`, `toReactive()` |

## Extension Hierarchy

```mermaid
flowchart TD
    Registry[useRegistry]
    Selection[useSelection]
    Single[useSingle]
    Step[useStep]
    Group[useGroup]
    Tokens[useTokens]
    Form[useForm]

    Registry --> Selection
    Registry --> Tokens
    Registry --> Form
    Selection --> Single
    Selection --> Group
    Single --> Step
```

> [!SUGGESTION] When should I use useSelection vs useSingle vs useGroup for my use case?

---

# Theming
URL: https://0.vuetifyjs.com/guide/theming

# Theming

v0 theming uses CSS custom properties for runtime theme switching. The theme plugin manages variable injection; you style with standard CSS.

> [!TIP]
> v0 is unopinionated—you define all theme colors. The examples below show common patterns, but the color names and values are entirely yours.

> [!SUGGESTION] How do I use v0 theming with Tailwind CSS instead of UnoCSS?

## Quick Start

### 1. Install Plugin

```ts main.ts
import { createApp } from 'vue'
import { createThemePlugin } from '@vuetify/v0'

const app = createApp(App)

app.use(
  createThemePlugin({
    default: 'light',
    themes: {
      light: {
        dark: false,
        colors: {
          primary: '#1976D2',
          secondary: '#424242',
          background: '#FFFFFF',
          surface: '#FFFFFF',
          error: '#B00020',
        },
      },
      dark: {
        dark: true,
        colors: {
          primary: '#2196F3',
          secondary: '#616161',
          background: '#121212',
          surface: '#1E1E1E',
          error: '#CF6679',
        },
      },
    },
  }),
)
```

### 2. Use in Components

```vue playground
<script setup>
  import { useTheme } from '@vuetify/v0'

  const theme = useTheme()
</script>

<template>
  <button @click="theme.cycle()">
    Current: {{ theme.selectedId }}
  </button>
</template>

<style>
  .card {
    background: var(--v0-surface);
    color: var(--v0-on-surface);
  }
</style>
```

## Theme API

```ts
const theme = useTheme()

// Read current theme
theme.selectedId.value   // 'light' | 'dark'
theme.selectedItem.value // Current theme ticket
theme.isDark.value       // boolean

// Switch themes
theme.cycle()            // Cycle through themes
theme.select('dark')     // Select specific theme

// Access theme values
theme.colors.value                          // Map of all theme colors
theme.colors.value[theme.selectedId.value]  // Current theme's colors
```

## CSS Variables

v0 injects variables with the `--v0-` prefix:

| Variable | Purpose |
| - | - |
| `--v0-primary` | Primary brand color |
| `--v0-secondary` | Secondary color |
| `--v0-background` | Page background |
| `--v0-surface` | Card/component background |
| `--v0-error` | Error state color |
| `--v0-on-primary` | Text on primary background |
| `--v0-on-surface` | Text on surface background |

### Using Variables

```css
.btn-primary {
  background: var(--v0-primary);
  color: var(--v0-on-primary);
}

.card {
  background: var(--v0-surface);
  border: 1px solid var(--v0-divider);
}
```

### UnoCSS Integration

Map v0 variables to UnoCSS theme colors for utility class support:

```ts uno.config.ts
import { defineConfig, presetUno } from 'unocss'

export default defineConfig({
  presets: [presetUno()],
  theme: {
    colors: {
      primary: 'var(--v0-primary)',
      secondary: 'var(--v0-secondary)',
      background: 'var(--v0-background)',
      surface: 'var(--v0-surface)',
      error: 'var(--v0-error)',
      'on-primary': 'var(--v0-on-primary)',
      'on-surface': 'var(--v0-on-surface)',
    },
  },
})
```

Now use standard utilities:

```html
<button class="bg-primary text-on-primary">Click me</button>
<div class="bg-surface text-on-surface border-error">Card</div>
```

Theme changes update automatically—the utilities reference CSS variables, not static values.

## Dark Mode

### Manual Toggle

```vue playground
<script setup>
  import { useTheme } from '@vuetify/v0'

  const theme = useTheme()
</script>

<template>
  <div class="bg-background min-h-100vh">
    <button @click="theme.cycle()">
      {{ theme.isDark ? 'Light' : 'Dark' }}
    </button>
  </div>
</template>
```

> [!SUGGESTION] How can I sync theme selection to localStorage and restore it on page load?

## Design Tokens with createTokens

For fine-grained token management beyond colors:

```ts
import { createTokens } from '@vuetify/v0'

const tokens = createTokens()

// Register tokens
tokens.register({ id: 'spacing-sm', value: '0.5rem' })
tokens.register({ id: 'spacing-md', value: '1rem' })
tokens.register({ id: 'radius-sm', value: '4px' })

// Aliases use {path} syntax in the value
tokens.register({ id: 'gap', value: '{spacing-md}' })

// Lookup resolves aliases
tokens.resolve('gap')  // '1rem'
```

### Token Categories

```ts
// Typography
tokens.register({ id: 'font-body', value: 'Inter, sans-serif' })
tokens.register({ id: 'font-size-sm', value: '0.875rem' })

// Spacing
tokens.register({ id: 'space-1', value: '0.25rem' })
tokens.register({ id: 'space-2', value: '0.5rem' })

// Shadows
tokens.register({ id: 'shadow-sm', value: '0 1px 2px rgba(0,0,0,0.1)' })
```

## Scoped Themes

Override theme for a subtree using the trinity pattern:

```ts
import { createThemeContext, createTheme } from '@vuetify/v0'

// Create a custom theme context with options
const [useTheme, provideTheme] = createThemeContext({
  default: 'custom',
  themes: {
    custom: {
      dark: false,
      colors: {
        primary: '#E91E63',  // Pink instead of blue
        secondary: '#9C27B0',
      },
    },
  },
})

// Provide to descendants
provideTheme()
```

## Best Practices

### 1. Semantic Color Names

```ts
// Good - semantic
themes: {
  light: { colors: { primary: '#1976D2', error: '#B00020' } },
}

// Avoid - literal
themes: {
  light: { colors: { blue: '#1976D2', red: '#B00020' } },
}
```

### 2. On-* Contrast Colors

Always define contrast colors for accessibility:

```ts
themes: {
  light: {
    colors: {
      primary: '#1976D2',
      'on-primary': '#FFFFFF',  // White text on primary
      surface: '#FFFFFF',
      'on-surface': '#212121',   // Dark text on surface
    },
  },
}
```

### 3. CSS Fallbacks

```css
.card {
  /* Fallback for missing variable */
  background: var(--v0-surface, #ffffff);
}
```

---

# Utilities
URL: https://0.vuetifyjs.com/guide/utilities

# Utilities

Standalone helpers for common UI patterns. These composables don't depend on context or plugins—use them anywhere.

## Overview

| Utility | Purpose |
| - | - |
| [createFilter](/composables/utilities/use-filter) | Filter arrays with search queries |
| [createPagination](/composables/utilities/use-pagination) | Page navigation state |
| [useVirtual](/composables/utilities/use-virtual) | Virtual scrolling for large lists |
| [createOverflow](/composables/utilities/use-overflow) | Compute visible item capacity |

> [!TIP]
> These utilities are standalone—they don't require plugins or context. Use them anywhere, including outside Vue components.

## createFilter

Filter arrays based on search queries:

```ts
import { createFilter } from '@vuetify/v0'

const items = ref(['Apple', 'Banana', 'Cherry'])
const query = ref('')

const filter = createFilter()
const { items: filtered } = filter.apply(query, items)

query.value = 'an'
filtered.value  // ['Banana']
```

### With Object Keys

```ts
const users = ref([
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' },
])

const filter = createFilter({
  keys: ['name', 'email'],
})

const query = ref('alice')
const { items: filtered } = filter.apply(query, users)
filtered.value  // [{ name: 'Alice', ... }]
```

### Filter Modes

```ts
const filter = createFilter({
  mode: 'intersection',  // 'some' | 'every' | 'union' | 'intersection'
  keys: ['name', 'tags'],
})
```

## createPagination

Pagination state management:

```ts
import { createPagination } from '@vuetify/v0'

const pagination = createPagination({
  size: 100,
  itemsPerPage: 10,
})

pagination.page.value     // 1
pagination.pages          // 10
pagination.isFirst.value  // true
pagination.isLast.value   // false

pagination.next()         // Go to page 2
pagination.prev()         // Go to page 1
pagination.select(5)      // Go to page 5
pagination.first()        // Go to page 1
pagination.last()         // Go to page 10
```

### With Reactive Size

```ts
const items = ref([...])

const pagination = createPagination({
  size: () => items.value.length,
  itemsPerPage: 20,
})
```

### Page Items

```ts
pagination.items.value  // [{ type: 'page', value: 1 }, { type: 'page', value: 2 }, ...]
```

## useVirtual

Virtual scrolling for large datasets:

```ts
import { useVirtual } from '@vuetify/v0'

const items = ref(Array.from({ length: 10000 }, (_, i) => `Item ${i}`))

// useVirtual takes items as first arg, options as second
const virtual = useVirtual(items, {
  itemHeight: 40,
})
```

```vue playground VirtualList.vue
<template>
  <div ref="virtual.element" style="height: 400px; overflow: auto;">
    <div :style="{ height: `${virtual.size}px`, paddingTop: `${virtual.offset}px` }">
      <div
        v-for="item in virtual.items"
        :key="item.index"
        style="height: 40px"
      >
        {{ item.raw }}
      </div>
    </div>
  </div>
</template>
```

### Variable Height

```ts
const virtual = useVirtual(items, {
  height: 400,  // Container height (or use element ref)
})
```

## createOverflow

Compute how many items fit in a container:

```ts
import { createOverflow } from '@vuetify/v0'

const container = ref<HTMLElement>()

const overflow = createOverflow({
  container,
  itemWidth: 100,
  gap: 8,
})

overflow.capacity.value       // Number of items that fit
overflow.isOverflowing.value  // Boolean: items exceed capacity
```

### Use Case: Responsive Chips

```vue playground ResponsiveChips.vue
<template>
  <div ref="container" class="flex gap-2">
    <span v-for="tag in visibleTags" :key="tag" class="chip">
      {{ tag }}
    </span>
    <span v-if="overflow.isOverflowing.value" class="chip">
      +{{ tags.length - overflow.capacity.value }}
    </span>
  </div>
</template>

<script setup>
  const tags = ['Vue', 'React', 'Angular', 'Svelte', 'Solid']
  const visibleTags = computed(() => tags.slice(0, overflow.capacity.value))
</script>
```

## Transformers

Value transformation utilities:

### toArray

Normalize any value to an array:

```ts
import { toArray } from '@vuetify/v0'

toArray('single')      // ['single']
toArray(['array'])     // ['array']
toArray(null)          // []
toArray(undefined)     // []
```

### toReactive

Convert ref objects to reactive proxies:

```ts
import { toReactive } from '@vuetify/v0'

const configRef = ref({ debug: false })

// Unwraps the ref and returns a reactive object
const config = toReactive(configRef)

config.debug  // Reactive access
```

## Best Practices

### Combine Utilities

```ts
// Filter + Paginate
const query = ref('')
const filter = createFilter()
const { items: filtered } = filter.apply(query, items)

const pagination = createPagination({
  size: () => filtered.value.length,
  itemsPerPage: 10,
})

const displayedItems = computed(() => {
  const start = pagination.pageStart.value
  const end = pagination.pageStop.value
  return filtered.value.slice(start, end)
})
```

### Virtual + Filter

```ts
const query = ref('')
const filter = createFilter()
const { items: filtered } = filter.apply(query, items)

const virtual = useVirtual(filtered, {
  itemHeight: 40,
})
```

> [!SUGGESTION] How do I combine filter, pagination, AND virtual scrolling together?

---

# Vuetify Mcp
URL: https://0.vuetifyjs.com/guide/vuetify-mcp

# Vuetify MCP

Vuetify MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants structured access to Vuetify and v0 APIs. Unlike [llms.txt](/guide/ai-tools), MCP provides real-time, queryable documentation.

## Quick Start

### Hosted Server (Recommended)

The fastest way to get started. No installation required:

```bash
claude mcp add --transport http vuetify-mcp https://mcp.vuetifyjs.com/mcp
```

### Local Installation

Run the server locally for offline access:

```bash
npx -y @vuetify/mcp
```

### Interactive Setup

Auto-detects your IDE and configures MCP:

```bash
# For hosted server
npx -y @vuetify/mcp config --remote

# For local server
npx -y @vuetify/mcp config
```

## IDE Configuration

Manual configuration for each IDE:

| IDE | Config File |
| - | - |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| VS Code | `~/.config/Code/User/settings.json` |
| Cursor | `~/.config/Cursor/User/mcp.json` |
| Windsurf | `~/.config/Windsurf/User/mcp.json` |
| Trae | `~/.config/Trae/User/mcp.json` |

### Hosted Configuration

```json
{
  "mcpServers": {
    "vuetify-mcp": {
      "url": "https://mcp.vuetifyjs.com/mcp"
    }
  }
}
```

### Local Configuration

```json
{
  "mcpServers": {
    "vuetify-mcp": {
      "command": "npx",
      "args": ["-y", "@vuetify/mcp"]
    }
  }
}
```

## Available Tools

### Vuetify 3 API

| Tool | Purpose |
| - | - |
| `get_component_api_by_version` | Props, events, slots for any component |
| `get_directive_api_by_version` | Directive info (v-ripple, v-scroll, etc.) |
| `get_vuetify_api_by_version` | Download full API types by version |

### Documentation

| Tool | Purpose |
| - | - |
| `get_installation_guide` | Setup for Vite, Nuxt, Laravel, CDN |
| `get_feature_guide` | Theming, i18n, accessibility guides |
| `get_frequently_asked_questions` | Common questions and answers |
| `get_release_notes_by_version` | Changelog for any version |

### v0 (Headless)

| Tool | Purpose |
| - | - |
| `get_vuetify0_composable_list` | List all composables by category |
| `get_vuetify0_composable_guide` | Detailed composable documentation |
| `get_vuetify0_component_list` | List all headless components |
| `get_vuetify0_component_guide` | Component documentation and examples |

> [!SUGGESTION] Which Vuetify MCP tools should I use for building components?

## Authentication

Some features require a Vuetify API key:

```json
{
  "mcpServers": {
    "vuetify-mcp": {
      "command": "npx",
      "args": ["-y", "@vuetify/mcp"],
      "env": {
        "VUETIFY_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Self-Hosting

Run an HTTP server for team access:

```bash
npx -y @vuetify/mcp --transport=http --port=3000 --host=0.0.0.0 --stateless
```

Then configure clients to use your server URL instead of `mcp.vuetifyjs.com`.

---

# components
URL: https://0.vuetifyjs.com/components

# Components

A collection of foundational components designed to be headless, accessible, and highly customizable.

## Primitives

Foundation components for building higher-level abstractions.

| Name | Description |
| - | - |
| [Atom](/components/primitives/atom) | Polymorphic element with dynamic `as` prop and renderless mode |

## Providers

Pure context providers for state management. Always renderless—they provide logic without rendering DOM elements.

| Name | Description |
| - | - |
| [Selection](/components/providers/selection) | Multi-selection state with v-model binding |
| [Single](/components/providers/single) | Single-selection with automatic deselection |
| [Group](/components/providers/group) | Multi-selection with tri-state support |
| [Step](/components/providers/step) | Sequential navigation (first, last, next, prev) |

## Semantic

Components with meaningful HTML defaults. Render semantic elements by default but support the `as` prop for customization.

| Name | Description |
| - | - |
| [Avatar](/components/semantic/avatar) | Image/fallback avatar with priority loading |
| [Pagination](/components/semantic/pagination) | Page navigation with semantic `<nav>` wrapper |

## Disclosure

Components for showing/hiding content.

| Name | Description |
| - | - |
| [ExpansionPanel](/components/disclosure/expansion-panel) | Accordion-style collapsible panels |
| [Popover](/components/disclosure/popover) | CSS anchor-positioned popup content |

---

# Expansion Panel
URL: https://0.vuetifyjs.com/components/disclosure/expansion-panel

<script setup>
import BasicExample from '@/examples/components/expansion-panel/basic.vue'
import BasicExampleRaw from '@/examples/components/expansion-panel/basic.vue?raw'
import AccordionExample from '@/examples/components/expansion-panel/accordion.vue'
import AccordionExampleRaw from '@/examples/components/expansion-panel/accordion.vue?raw'
import CollapsibleExample from '@/examples/components/expansion-panel/basic.vue'
import CollapsibleExampleRaw from '@/examples/components/expansion-panel/basic.vue?raw'
</script>

# ExpansionPanel

A component for creating accordion-style expansion panels with proper ARIA support.

## Usage

The ExpansionPanel component provides a wrapper and item pattern for managing expansion state in accordion-style interfaces. It uses the `useSelection` composable internally and provides full v-model support with automatic state synchronization.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { ExpansionPanel } from '@vuetify/v0'
</script>

<template>
  



---

# Popover
URL: https://0.vuetifyjs.com/components/disclosure/popover

<script setup>
  //
</script>

# Popover

A headless component for creating popovers and tooltips using modern CSS anchor positioning.

## Usage

The Popover component leverages the CSS Anchor Positioning API to create popovers, tooltips, and dropdown menus without JavaScript-based positioning. It provides v-model support for open/closed state management.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Popover } from '@vuetify/v0'
</script>

<template>
  <Popover.Root>
    

    
  </Popover.Root>
</template>
```

## Positioning

The Popover component uses the CSS Anchor Positioning API for positioning. The `positionArea` prop accepts standard CSS values:

| Value | Description |
|---|---|
| `top` | Position above the anchor |
| `bottom` | Position below the anchor |
| `left` | Position to the left of the anchor |
| `right` | Position to the right of the anchor |
| `top left` | Position above and to the left |
| `top right` | Position above and to the right |
| `bottom left` | Position below and to the left |
| `bottom right` | Position below and to the right |

The `positionTry` prop provides fallback positioning when the primary position doesn't fit.

---

# Atom
URL: https://0.vuetifyjs.com/components/primitives/atom

<script setup>
import BasicExample from '@/examples/components/atom/basic.vue'
import BasicExampleRaw from '@/examples/components/atom/basic.vue?raw'
</script>

# Atom

The foundational building block for dynamic element rendering with renderless capabilities.

## Usage

The Atom component provides dynamic element rendering and is used as the foundation for all other components in Vuetify0. It supports polymorphic rendering through the `as` prop and can render as any HTML element or Vue component.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Atom } from '@vuetify/v0'
</script>

<template>
  
</template>
```



---

# Group
URL: https://0.vuetifyjs.com/components/providers/group

<script setup>
import BasicExample from '@/examples/components/group/basic.vue'
import BasicExampleRaw from '@/examples/components/group/basic.vue?raw'
import SelectAllExample from '@/examples/components/group/select-all.vue'
import SelectAllExampleRaw from '@/examples/components/group/select-all.vue?raw'
</script>

# Group

A headless component for managing multi-selection with batch operations and tri-state support.

## Usage

The Group component is a specialization of Selection that enforces multi-selection behavior and supports batch operations on arrays of IDs. It always uses array-based v-model binding.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Group } from '@vuetify/v0'
</script>

<template>
  



---

# Selection
URL: https://0.vuetifyjs.com/components/providers/selection

<script setup>
import BasicExample from '@/examples/components/selection/basic.vue'
import BasicExampleRaw from '@/examples/components/selection/basic.vue?raw'
import SingleExample from '@/examples/components/selection/single.vue'
import SingleExampleRaw from '@/examples/components/selection/single.vue?raw'
import MandatoryExample from '@/examples/components/selection/mandatory.vue'
import MandatoryExampleRaw from '@/examples/components/selection/mandatory.vue?raw'
import DisabledExample from '@/examples/components/selection/disabled.vue'
import DisabledExampleRaw from '@/examples/components/selection/disabled.vue?raw'
</script>

# Selection

A headless component for managing selection state in collections with support for single and multi-selection patterns.

## Usage

The Selection component provides a wrapper and item pattern for managing selection state in collections. It uses the `useSelection` composable internally and provides full v-model support with automatic state synchronization.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Selection } from '@vuetify/v0'
</script>

<template>
  

### Mandatory Selection

### Disabled Items



---

# Single
URL: https://0.vuetifyjs.com/components/providers/single

<script setup>
import BasicExample from '@/examples/components/single/basic.vue'
import BasicExampleRaw from '@/examples/components/single/basic.vue?raw'
</script>

# Single

A headless component for managing single-selection with automatic deselection of previous items.

## Usage

The Single component is a specialization of Selection that enforces single-selection behavior. When an item is selected, any previously selected item is automatically deselected.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Single } from '@vuetify/v0'
</script>

<template>
  <Single.Root>
    

    
  </Single.Root>
</template>
```



---

# Step
URL: https://0.vuetifyjs.com/components/providers/step

<script setup>
import BasicExample from '@/examples/components/step/basic.vue'
import BasicExampleRaw from '@/examples/components/step/basic.vue?raw'
</script>

# Step

A headless component for navigation through multi-step processes like wizards and forms.

## Usage

The Step component extends Single with navigation methods for moving through a sequence of items. It provides methods for first, last, next, previous, and step-by-count navigation with automatic disabled item skipping.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Step } from '@vuetify/v0'
</script>

<template>
  <Step.Root>
    

    
  </Step.Root>
</template>
```

## Navigation

The Step component provides several navigation methods:

| Method | Description |
|---|---|
| `first()` | Go to the first non-disabled item |
| `last()` | Go to the last non-disabled item |
| `next()` | Go to the next non-disabled item |
| `prev()` | Go to the previous non-disabled item |
| `step(count)` | Step forward (positive) or backward (negative) by count |

All navigation methods automatically skip disabled items.

---

# Avatar
URL: https://0.vuetifyjs.com/components/semantic/avatar

<script setup>
import BasicExample from '@/examples/components/avatar/basic.vue'
import BasicExampleRaw from '@/examples/components/avatar/basic.vue?raw'
</script>

# Avatar

A headless component for managing image loading with priority-based fallback system.

## Usage

The Avatar component provides a robust image loading system with automatic fallback handling. It manages multiple image sources with priority ordering and only displays the highest-priority loaded image or fallback content.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Avatar } from '@vuetify/v0'
</script>

<template>
  <Avatar.Root>
    

    
  </Avatar.Root>
</template>
```

## Priority System

The Avatar component uses a priority-based system to determine which content to display:

1. Images register with a `priority` value (default: `0`)
2. Fallbacks register with the lowest implicit priority
3. When an image loads successfully, it becomes selectable
4. The highest-priority loaded image is displayed
5. If all images fail, the fallback is shown

```vue PriorityExample
<template>
  <Avatar.Root>
    <!-- High-res preferred when available -->
    
    <!-- Low-res as backup -->
    
    <!-- Fallback if both fail -->
    <Avatar.Fallback>JD</Avatar.Fallback>
  </Avatar.Root>
</template>
```

---

# Pagination
URL: https://0.vuetifyjs.com/components/semantic/pagination

<script setup>
import BasicExample from '@/examples/components/pagination/basic.vue'
import BasicExampleRaw from '@/examples/components/pagination/basic.vue?raw'
</script>

# Pagination

A headless component for creating page navigation with proper ARIA support.

## Usage

The Pagination component provides a compound component pattern for building page navigation interfaces. It uses the [usePagination](/composables/utilities/use-pagination) and [useOverflow](/composables/utilities/use-overflow) composable internally.

## Anatomy

```vue Anatomy playground
<script setup lang="ts">
  import { Pagination } from '@vuetify/v0'
</script>

<template>
  <Pagination.Root>
    

    

    

    

    

    
  </Pagination.Root>
</template>
```

> For responsive sizing to work accurately, **all pagination buttons must have the same width**. The component measures a sample button and uses that width to calculate how many buttons fit. If buttons have variable widths (e.g., single-digit "1" vs double-digit "50"), the calculation will be inaccurate and items may overflow or leave excess space.

## Recipes

Examples of common Pagination structures:

### RouterLink

Use the **as** prop to render pagination items as `RouterLink` components.

```vue RouterLink
<script setup lang="ts">
  import { Pagination } from '@vuetify/v0'
  import { RouterLink } from 'vue-router'
</script>

<template>
  <Pagination.Root :size="200" v-slot="{ items }">
    <Pagination.First :as="RouterLink" to="...">«</Pagination.First>

    <Pagination.Prev :as="RouterLink" to="...">‹</Pagination.Prev>

    <template v-for="(item, index) in items" :key="index">
      

      <Pagination.Item
        v-else
        :as="RouterLink"
        :value="item.value"
        to="..."
      >
        {{ item.value }}
      </Pagination.Item>
    </template>

    <Pagination.Next :as="RouterLink" to="...">›</Pagination.Next>

    <Pagination.Last :as="RouterLink" to="...">»</Pagination.Last>
  </Pagination.Root>
</template>
```

### Unordered list

Pagination example with nav, ul, and li elements.

```vue UnorderedList
<script setup lang="ts">
  import { Pagination } from '@vuetify/v0'
</script>

<template>
  <Pagination.Root :size="200" v-slot="{ items }">
    <ul>
      <li>
        <Pagination.First as="a" href="...">«</Pagination.First>
      </li>

      <li>
        <Pagination.Prev as="a" href="...">‹</Pagination.Prev>
      </li>

      <li v-for="(item, index) in items" :key="index">
        

        <Pagination.Item
          v-else
          as="a"
          :value="item.value"
          href="..."
        >
          {{ item.value }}
        </Pagination.Item>
      </li>

      <li>
        <Pagination.Next as="a" href="...">›</Pagination.Next>
      </li>

      <li>
        <Pagination.Last as="a" href="...">»</Pagination.Last>
      </li>
    </ul>
  </Pagination.Root>
</template>
```

---

# composables
URL: https://0.vuetifyjs.com/composables

# Composables

v0 composables are the building blocks for headless UI. Components wrap these composables—you can use either approach.

## Composable Hierarchy

```
createContext ─── Type-safe provide/inject
      │
      └──► createTrinity ─── [use, provide, context] tuple
                │
                └──► createPlugin ─── Vue plugin factory

useRegistry ─── Base collection management
      │
      ├──► useSelection ─── + selectedIds Set
      │         │
      │         ├──► useSingle ─── Single selection
      │         │         │
      │         │         └──► useStep ─── + navigation
      │         │
      │         └──► useGroup ─── + tri-state, batch ops
      │
      ├──► useTokens ─── + alias resolution
      │
      └──► useForm ─── + validation
```

## Choosing a Composable

| Need | Use | Category |
| - | - | - |
| Radio buttons, tabs | `useSingle` | selection |
| Checkboxes, multi-select | `useGroup` | selection |
| Wizard, stepper | `useStep` | selection |
| Form validation | `useForm` | forms |
| Design tokens | `useTokens` | registration |
| Dark/light mode | `useTheme` | plugins |
| i18n, RTL | `useLocale` | plugins |
| Filter/search | `useFilter` | utilities |
| Pagination | `usePagination` | utilities |
| Large lists | `useVirtual` | utilities |

## Foundation

Core factories that provide the foundation for all other composables.

| Name | Description |
| - | - |
| [createContext](/composables/foundation/create-context) | Create reusable context to share state across components |
| [createPlugin](/composables/foundation/create-plugin) | Create Vue plugins with standardized patterns |
| [createTrinity](/composables/foundation/create-trinity) | Create context provider/consumer pattern utilities |

## Registration

Collection management and data structure primitives.

| Name | Description |
| - | - |
| [useRegistry](/composables/registration/use-registry) | Foundation for registration-based systems |
| [useProxyRegistry](/composables/registration/use-proxy-registry) | Proxy-based registry with automatic reactivity |
| [useQueue](/composables/registration/use-queue) | Time-based queue management with automatic timeouts |
| [useTimeline](/composables/registration/use-timeline) | Bounded undo/redo system with fixed-size history |
| [useTokens](/composables/registration/use-tokens) | Design token management system |

## Selection

State management for single and multi-selection patterns.

| Name | Description |
| - | - |
| [useSelection](/composables/selection/use-selection) | General selection state management |
| [useSingle](/composables/selection/use-single) | Single-selection with automatic deselection |
| [useGroup](/composables/selection/use-group) | Multi-selection with tri-state support |
| [useStep](/composables/selection/use-step) | Sequential navigation for wizards and steppers |

## Forms

Form state management and model binding utilities.

| Name | Description |
| - | - |
| [useForm](/composables/forms/use-form) | Form state management and validation |
| [useProxyModel](/composables/forms/use-proxy-model) | Bridge selection context to v-model binding |

## System

Browser API wrappers with automatic lifecycle cleanup.

| Name | Description |
| - | - |
| [useEventListener](/composables/system/use-event-listener) | Handle DOM events with automatic cleanup |
| [useIntersectionObserver](/composables/system/use-intersection-observer) | Intersection Observer API for visibility detection |
| [useKeydown](/composables/system/use-keydown) | Handle keyboard events with automatic cleanup |
| [useMutationObserver](/composables/system/use-mutation-observer) | Mutation Observer API for DOM change detection |
| [useResizeObserver](/composables/system/use-resize-observer) | Resize Observer API for element size changes |
| [useToggleScope](/composables/system/use-toggle-scope) | Conditional effect scope management |

## Plugins

Application-level features installable via Vue plugins.

| Name | Description |
| - | - |
| [useBreakpoints](/composables/plugins/use-breakpoints) | Responsive breakpoint detection |
| [useFeatures](/composables/plugins/use-features) | Feature flags and A/B testing |
| [useHydration](/composables/plugins/use-hydration) | SSR hydration management |
| [useLocale](/composables/plugins/use-locale) | Internationalization system |
| [useLogger](/composables/plugins/use-logger) | Logging system with multiple adapters |
| [usePermissions](/composables/plugins/use-permissions) | Role-based access control |
| [useStorage](/composables/plugins/use-storage) | Reactive browser storage interface |
| [useTheme](/composables/plugins/use-theme) | Theme management with CSS custom properties |

## Utilities

Standalone helpers for common UI patterns.

| Name | Description |
| - | - |
| [useFilter](/composables/utilities/use-filter) | Filter arrays based on search queries |
| [useOverflow](/composables/utilities/use-overflow) | Compute item capacity for responsive truncation |
| [usePagination](/composables/utilities/use-pagination) | Pagination state with navigation methods |
| [useVirtual](/composables/utilities/use-virtual) | Virtual scrolling for large lists |

## Transformers

Value transformation utilities.

| Name | Description |
| - | - |
| [toArray](/composables/transformers/to-array) | Convert any value to an array |
| [toReactive](/composables/transformers/to-reactive) | Convert MaybeRef objects to reactive proxies |

---

# Use Form
URL: https://0.vuetifyjs.com/composables/forms/use-form

# useForm

A composable for building reactive forms with validation, field registration, and submission handling. Built on top of the registry system for managing form fields.

## Usage

The `useForm` composable provides a powerful interface for managing form state, validation, and submission. It extends the registry pattern to handle form-specific requirements like validation rules, error states, and field lifecycle management.

```ts
import { useForm } from '@vuetify/v0'

const form = useForm()

const email = form.register({
  id: 'email',
  value: '',
  rules: [
    (value) => value.includes('@') || 'Must be a valid email',
    (value) => value.length > 0 || 'Required'
  ]
})

console.log(email.value) // ''
console.log(email.errors.value) // []
```



---

# Use Proxy Model
URL: https://0.vuetifyjs.com/composables/forms/use-proxy-model

# useProxyModel

A composable for syncing refs bidirectionally with selection contexts, enabling seamless v-model integration with selection state.

## Usage

The `useProxyModel` composable syncs an existing ref (like from `defineModel()`) with a selection context bidirectionally. Changes in either direction automatically propagate.

```ts
import { ref } from 'vue'
import { createSelection, useProxyModel } from '@vuetify/v0'

const model = ref<string>()
const selection = createSelection({ events: true })

selection.onboard([
  { id: 'apple', value: 'Apple' },
  { id: 'banana', value: 'Banana' },
])

// Sync model with selection
const stop = useProxyModel(selection, model)

model.value = 'Apple'
console.log(selection.selectedIds) // Set { 'apple' }

selection.select('banana')
console.log(model.value) // 'Banana'
```

## With defineModel

Perfect for Vue components with v-model:

```vue UseProxyModel
<script setup lang="ts">
  import { createSelection, useProxyModel } from '@vuetify/v0'

  const model = defineModel<string>()
  const selection = createSelection({ events: true })

  selection.onboard([
    { id: '1', value: 'Option 1' },
    { id: '2', value: 'Option 2' },
  ])

  useProxyModel(selection, model)
</script>

<template>
  <div>
    <button
      v-for="item in selection.entries.value"
      :key="item[0]"
      @click="selection.toggle(item[0])"
    >
      {{ item[1].value }}
    </button>
  </div>
</template>
```

## Examples

### Multi-select with Array Mutations

```ts
const model = ref<string[]>([])
useProxyModel(selection, model, { multiple: true })

selection.onboard([
  { id: 'a', value: 'A' },
  { id: 'b', value: 'B' },
])

// Array mutations sync automatically
model.value.push('A')
console.log(selection.selectedIds) // Set { 'a' }

model.value.splice(0, 1, 'B')
console.log(selection.selectedIds) // Set { 'b' }
```

### Transform Functions

```ts
const model = ref<string>()

useProxyModel(selection, model, {
  transformIn: (val) => String(val).toUpperCase(),
  transformOut: (val) => String(val).toLowerCase(),
})

selection.onboard([
  { id: '1', value: 'HELLO' },
])

model.value = 'hello' // Transforms to 'HELLO' before lookup
console.log(selection.selectedIds) // Set { '1' }
console.log(model.value) // 'hello' (transformed output)
```

### Late Registration

```ts
const model = ref<string>('Item 2')
useProxyModel(selection, model)

// Item 2 doesn't exist yet, but will be auto-selected when registered
setTimeout(() => {
  selection.register({ id: '2', value: 'Item 2' })
  console.log(selection.selectedIds) // Set { '2' }
}, 1000)
```

### Manual Cleanup

```ts
const stop = useProxyModel(selection, model)

// Later, stop syncing
stop()

// Changes no longer sync
model.value = 'New Value'
// selection.selectedIds unchanged
```

---

# Create Context
URL: https://0.vuetifyjs.com/composables/foundation/create-context

# createContext

The `createContext` factory function is at the heart of all functionality in Vuetify0. It is a small wrapper around the Vue 3 [provide](https://vuejs.org/guide/components/provide-inject.html#provide) and [inject](https://vuejs.org/guide/components/provide-inject.html#inject) APIs, allowing you to create a context that can be shared across components.

## Usage

```ts
import { shallowRef } from 'vue'
import { createContext } from '@vuetify/v0'
import type { ShallowRef } from 'vue'

interface MyContext {
  isDisabled: ShallowRef<boolean>
}

const [useContext, provideContext] = createContext<MyContext>('namespace')

provideContext({ isDisabled: shallowRef(false) })

export { useContext }
```



---

# Create Plugin
URL: https://0.vuetifyjs.com/composables/foundation/create-plugin

# createPlugin

This composable allows you to create a Vue plugin with specific functionality that can be registered and used within your application.

## Usage { id="usage" }

Use in conjunction with the [createContext](/composables/foundation/create-context "createContext Documentation") composable to make [Vue plugins](https://vuejs.org/guide/reusability/plugins "Vue Plugins Documentation") that work seemlessly with [Vue Provide / Inject](https://vuejs.org/guide/components/provide-inject "Vue Provide / Inject Documentation").

```ts
import { createContext, createPlugin } from '@vuetify/v0'

interface MyPluginContext {
  app: string
}

// use is the inject function and provide is the provide function
export const [useMyContext, provideMyContext] = createContext<MyPluginContext>('provide-namespace')

export function createMyPlugin () {
  const context = {
    app: 'my-app'
  }

  return createPlugin({
    namespace: 'provide-namespace',
    provide: (app: App) => {
      provideMyContext(context, app)
    },
    setup: (app: App) => {
      // For everything else not provide related
    }
  })
}
```

> The **setup** and **provide** functions do the same thing, they are separated for semantic purposes.

Then, in your main application file, register the plugin like so:

```ts { resource="src/main.ts" }
import { createApp } from 'vue'
import { createMyPlugin } from './path/to/plugin'

const app = createApp(App)

app.use(createMyPlugin())
```

Now, whenever your application starts, the plugin is registered and the context is provided. Use the `useMyContext` function to access this context in any component:

```vue { resource="src/components/MyComponent.vue" }
<template>
  <div>{{ context.app }}</div>
</template>

<script setup lang="ts">
  import { useMyContext } from './path/to/plugin'

  const context = useMyContext()
</script>
```



---

# Create Trinity
URL: https://0.vuetifyjs.com/composables/foundation/create-trinity

# createTrinity

The **createTrinity** factory function is a type-safe utility for generating a 3-item tuple—called a **trinity**—which contains a context consumer, a provider, and the underlying context object.

## Usage

The trinity pattern is the marrying of provide and inject with a context object. It provides a clean and type safe way to create a sharable singleton state.

```ts
import { createContext, createTrinity } from '@vuetify/v0'
import { ref } from 'vue'

interface User {
  id: string
  name: string
}

interface UserContext {
  user: Ref<User>
  updateUser: (user: User) => void
}

function createUserContext() {
  const [useContext, provideContext] = createContext<UserContext>('user')

  const user = ref<User>({ id: '123', name: 'John Doe' })

  function updateUser(newUser: User) {
    user.value = newUser
  }

  const context: UserContext = {
    user,
    updateUser
  }

  return createTrinity<UserContext>(useContext, provideContext, context)
}

export const [useUser, provideUser, defaultUserContext] = createUserContext()
```



---

# Use Breakpoints
URL: https://0.vuetifyjs.com/composables/plugins/use-breakpoints

# useBreakpoints

The `useBreakpoints` composable provides comprehensive responsive design capabilities through reactive viewport dimension detection. It automatically tracks window size changes and provides boolean flags for current breakpoint ranges, enabling mobile-first and responsive layouts.

## Installation

First, install the breakpoints plugin in your application:

```ts
import { createApp } from 'vue'
import { createBreakpointsPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createBreakpointsPlugin({
    mobileBreakpoint: 'md',
    breakpoints: {
      xs: 0,
      sm: 600,
      md: 960,
      lg: 1280,
      xl: 1920,
      xxl: 2560,
    },
  })
)

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useBreakpoints` composable in any component:

```vue UseBreakpoints
<script setup lang="ts">
  import { useBreakpoints } from '@vuetify/v0'

  const breakpoints = useBreakpoints()
</script>

<template>
  <div>
    <nav v-if="breakpoints.mdAndUp">
      <!-- Desktop navigation -->
    </nav>
    <nav v-else>
      <!-- Mobile navigation -->
    </nav>

    <p v-if="breakpoints.isMobile">Mobile layout active</p>
    <p>Current breakpoint: {{ breakpoints.name }}</p>
    <p>Viewport: {{ breakpoints.width }} x {{ breakpoints.height }}</p>
  </div>
</template>
```



---

# Use Features
URL: https://0.vuetifyjs.com/composables/plugins/use-features

# useFeatures

Manage feature flags and simple variations across your app. Register features, toggle them, and query a variation value for A/B-style behavior.

## Usage

Install the Features plugin once, then access the context anywhere via `createFeatures`.

```ts
import { createApp } from 'vue'
import { createFeaturesPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createFeaturesPlugin({
    features: {
      analytics: true,
      debug_mode: false,
      notifications: false,
      search: { $value: true, $variation: 'v2' },
    },
  })
)

app.mount('#app')
```

Now in any component, access current feature flags and variations:

```vue UseFeatures
<script setup lang="ts">
  import { useFeatures } from '@vuetify/v0'

  const features = useFeatures()
</script>

<template>
  <div>
    <p>Analytics: {{ features.get('analytics') }}</p>
    <p>Debug Mode: {{ features.get('debug_mode') }}</p>
    <p>Notifications: {{ features.get('notifications') }}</p>
    <p>Search Variation: {{ features.variation('search', 'v1') }}</p>
  </div>
</template>
```

Optionally register features at runtime:

```vue UseFeatures
<script setup lang="ts">
  import { useFeatures } from '@vuetify/v0'

  const features = useFeatures()

  // Register at runtime
  features.register({ id: 'beta', value: false })

  // Enable/disable via selection helpers
  features.select('beta')
  features.unselect('analytics')
</script>
```



---

# Use Hydration
URL: https://0.vuetifyjs.com/composables/plugins/use-hydration

# useHydration

The `useHydration` composable provides SSR hydration state management, allowing you to detect when your application has been hydrated on the client side. This is essential for preventing hydration mismatches and controlling when browser-only features should activate.

## Installation

First, install the hydration plugin in your application:

```ts
import { createApp } from 'vue'
import { createHydrationPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(createHydrationPlugin())

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useHydration` composable in any component:

```vue UseHydration
<script setup lang="ts">
  import { useHydration } from '@vuetify/v0'

  const hydration = useHydration()
</script>

<template>
  <div>
    <p v-if="hydration.isHydrated.value">
      Application is hydrated - browser features available
    </p>
    <p v-else>
      Rendering on server or waiting for hydration
    </p>
  </div>
</template>
```

## How Hydration Works

The hydration plugin automatically detects when the root component has mounted and marks the application as hydrated:

1. During SSR, `isHydrated` is `false`
2. When the root component mounts on the client, the plugin calls `hydrate()`
3. `isHydrated` becomes `true`, signaling that browser APIs are safe to use
4. Components that depend on hydration state can now activate browser-only features

The plugin uses a Vue mixin to detect the root component mount:

```ts
app.mixin({
  mounted() {
    if (this.$parent !== null) return // Skip child components
    context.hydrate() // Only hydrate on root mount
  }
})
```

---

# Use Locale
URL: https://0.vuetifyjs.com/composables/plugins/use-locale

# useLocale

The `useLocale` composable provides comprehensive internationalization (i18n) capabilities, allowing you to manage multiple locales, switch between them dynamically, and translate messages with variable replacement and message linking. Built on `useSingle` for single-locale selection and supports custom adapters for integration with different i18n libraries.

## Installation

First, install the locale plugin in your application:

```ts
import { createApp } from 'vue'
import { createLocalePlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createLocalePlugin({
    default: 'en',
    fallback: 'en',
    messages: {
      en: {
        hello: 'Hello',
        welcome: 'Welcome, {name}!',
        greeting: 'Hello, {0}! You have {1} messages.',
      },
      es: {
        hello: 'Hola',
        welcome: '¡Bienvenido, {name}!',
        greeting: '¡Hola, {0}! Tienes {1} mensajes.',
      },
      fr: {
        hello: 'Bonjour',
        welcome: 'Bienvenue, {name}!',
        greeting: 'Bonjour, {0}! Vous avez {1} messages.',
      },
    },
  })
)

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useLocale` composable in any component:

```vue UseLocale
<script setup lang="ts">
  import { useLocale } from '@vuetify/v0'

  const locale = useLocale()

  function changeLocale(id: string) {
    locale.select(id)
  }
</script>

<template>
  <div>
    <h1>{{ locale.t('hello') }}</h1>
    <p>{{ locale.t('welcome', { name: 'John' }) }}</p>

    <button @click="changeLocale('en')">English</button>
    <button @click="changeLocale('es')">Español</button>
    <button @click="changeLocale('fr')">Français</button>
  </div>
</template>
```



---

# Use Logger
URL: https://0.vuetifyjs.com/composables/plugins/use-logger

# useLogger

The `useLogger` composable provides a flexible, adapter-based logging system for Vue applications. It supports multiple log levels, runtime enable/disable toggling, and integrates seamlessly with popular logging libraries like Consola and Pino through a simple adapter pattern.

## Installation

First, install the logger plugin in your application:

```ts
import { createApp } from 'vue'
import { createLoggerPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createLoggerPlugin({
    level: 'info',
    enabled: true,
  })
)

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useLogger` composable in any component:

```vue UseLogger
<script setup lang="ts">
  import { useLogger } from '@vuetify/v0'

  const logger = useLogger()

  logger.info('Component mounted')
  logger.debug('Debug information', { userId: 123 })
  logger.warn('Warning message')
  logger.error('Error occurred', new Error('Something went wrong'))
</script>

<template>
  <div>
    <h1>Check the console for logs</h1>
  </div>
</template>
```



---

# Use Permissions
URL: https://0.vuetifyjs.com/composables/plugins/use-permissions

# usePermissions

Manage role-based permissions across your app. Register permissions for roles, actions, and subjects with optional context-aware conditions.

## Usage

Install the Permissions plugin once, then access the context anywhere via `createPermissions`.

```ts
import { createApp } from 'vue'
import { createPermissionsPlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createPermissionsPlugin({
    permissions: {
      admin: [
        [['read', 'write'], 'user', true],
        [['read', 'write'], 'post', true],
        ['delete', ['user', 'post'], true],
      ],
      editor: [
        [['read', 'write'], 'post', true],
        ['read', 'user', true],
        ['delete', 'post', (context) => context.isOwner],
      ],
      viewer: [
        ['read', ['user', 'post'], true],
      ],
    },
  })
)

app.mount('#app')
```

Now in any component, check permissions for specific roles:

```vue UsePermissions
<script setup lang="ts">
  import { usePermissions } from '@vuetify/v0'

  const permissions = usePermissions()
  const currentUser = { role: 'editor', id: 'user123' }
</script>

<template>
  <div>
    <button v-if="permissions.can('admin', 'delete', 'user')">
      Delete User (Admin Only)
    </button>

    <button v-if="permissions.can('editor', 'write', 'post')">
      Edit Post
    </button>

    <button
      v-if="permissions.can('editor', 'delete', 'post', { isOwner: true })"
    >
      Delete Own Post
    </button>
  </div>
</template>
```

Optionally register permissions at runtime:

```vue UsePermissions
<script setup lang="ts">
  import { usePermissions } from '@vuetify/v0'

  const permissions = usePermissions()

  // Register permission at runtime
  permissions.register({
    id: 'moderator.ban.user',
    value: (context) => context.userLevel < 3
  })

  // Check the permission
  const canBan = permissions.can('moderator', 'ban', 'user', { userLevel: 2 })
</script>
```

## Examples

### Basic RBAC Setup

```ts
const permissions = {
  admin: [
    [['create', 'read', 'update', 'delete'], ['user', 'post', 'comment'], true],
  ],
  moderator: [
    [['read', 'update', 'delete'], ['post', 'comment'], true],
    ['read', 'user', true],
  ],
  user: [
    ['read', ['post', 'comment'], true],
    [['create', 'update'], 'post', (context) => context.userId === context.authorId],
  ],
}
```

### Context-Aware Permissions

```ts
const permissions = {
  editor: [
    ['edit', 'post', (context) => {
      return context.post.authorId === context.currentUserId ||
             context.currentUser.isAdmin
    }],
    ['publish', 'post', (context) => {
      return context.post.status === 'draft' &&
             context.currentUser.department === 'editorial'
    }],
  ],
}
```

---

# Use Storage
URL: https://0.vuetifyjs.com/composables/plugins/use-storage

# useStorage

The `useStorage` composable provides reactive storage management with support for multiple storage backends (localStorage, sessionStorage, memory). Built with an adapter pattern for flexibility, it automatically serializes values, manages reactive refs, and provides SSR-safe operations.

## Installation

First, install the storage plugin in your application:

```ts
import { createApp } from 'vue'
import { createStoragePlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

// Use default settings (localStorage in browser, memory in SSR)
app.use(createStoragePlugin())

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useStorage` composable in any component:

```vue UseStorage
<script setup lang="ts">
  import { useStorage } from '@vuetify/v0'

  const storage = useStorage()

  // Get a reactive ref for a storage key
  const username = storage.get('username', 'Guest')

  // Update the value (automatically persists to storage)
  function updateUsername(name: string) {
    username.value = name
  }
</script>

<template>
  <div>
    <h1>Welcome, {{ username }}!</h1>
    <input v-model="username" placeholder="Enter your name" />
  </div>
</template>
```



---

# Use Theme
URL: https://0.vuetifyjs.com/composables/plugins/use-theme

# useTheme

The `useTheme` composable provides comprehensive theme management capabilities, allowing you to register multiple themes, switch between them dynamically, and automatically generate CSS custom properties. Built on `useSingle` for single-theme selection and `useTokens` for design token alias resolution.

## Installation

First, install the theme plugin in your application:

```ts
import { createApp } from 'vue'
import { createThemePlugin } from '@vuetify/v0'
import App from './App.vue'

const app = createApp(App)

app.use(
  createThemePlugin({
    default: 'light',
    themes: {
      light: {
        dark: false,
        colors: {
          primary: '#3b82f6',
          secondary: '#8b5cf6',
          background: '#ffffff',
          surface: '#f5f5f5',
        },
      },
      dark: {
        dark: true,
        colors: {
          primary: '#60a5fa',
          secondary: '#a78bfa',
          background: '#1e293b',
          surface: '#334155',
        },
      },
    },
  })
)

app.mount('#app')
```

## Usage

Once the plugin is installed, use the `useTheme` composable in any component:

```vue UseTheme
<script setup lang="ts">
  import { useTheme } from '@vuetify/v0'

  const theme = useTheme()

  function toggleTheme() {
    theme.cycle(['light', 'dark'])
  }
</script>

<template>
  <div>
    <h1>Current Theme: {{ theme.selectedId }}</h1>
    <p>Dark mode: {{ theme.isDark ? 'enabled' : 'disabled' }}</p>
    <button @click="toggleTheme">Toggle Theme</button>
  </div>
</template>
```

## Adapter Pattern

The adapter pattern allows you to customize how theme colors are transformed into CSS variables. This provides flexibility for different styling strategies and frameworks.

### Default Adapter

By default, `useTheme` uses `Vuetify0ThemeAdapter`, which:
- Generates CSS custom properties (e.g., `--v0-primary: #3b82f6`)
- Injects them into a `<style>` element in the document head
- Scopes variables using data attributes (e.g., `[data-theme="light"]`)
- Sets the `data-theme` attribute on the target element
- Sets the CSS `color-scheme` property based on theme's `dark` setting
- Supports SSR with head integration
- Supports CSP nonces for security

### Adapter Interface

All adapters must implement the `ThemeAdapterInterface`:

```ts
  interface ThemeAdapterSetupContext {
    colors: ComputedRef<Record<string, Colors>>
    selectedId: Ref<ID | null | undefined>
    isDark: Readonly<Ref<boolean>>
  }

  interface ThemeAdapterInterface {
    setup: <T extends ThemeAdapterSetupContext>(
      app: App,
      context: T,
      target?: string | HTMLElement | null
    ) => void
    update: (colors: Record<string, Colors>, isDark?: boolean) => void
  }

  type Colors = {
    [key: string]: string
  }
```

The adapter provides two methods:
- `setup(app, context, target)`: Called once during plugin initialization to set up watchers and DOM manipulation
- `update(colors, isDark)`: Called to update CSS when colors or dark mode changes

### Creating Custom Adapters

#### Option 1: Extend ThemeAdapter (Recommended)

Extend the base `ThemeAdapter` class for CSS generation utilities:

```ts
  import { ThemeAdapter } from '@vuetify/v0'
  import { watch, onScopeDispose } from 'vue'
  import type { App } from 'vue'
  import type { ThemeAdapterSetupContext, Colors } from '@vuetify/v0'

  class MyThemeAdapter extends ThemeAdapter {
    constructor() {
      super('my-prefix') // CSS variable prefix
    }

    setup<T extends ThemeAdapterSetupContext>(
      app: App,
      context: T,
      target?: string | HTMLElement | null
    ): void {
      // Set up watchers for reactive updates
      const stopWatch = watch([context.colors, context.isDark], ([colors, isDark]) => {
        this.update(colors, isDark)
      }, { immediate: true })

      onScopeDispose(stopWatch, true)

      // Optional: Set data-theme on target element
      if (target) {
        const el = typeof target === 'string' ? document.querySelector(target) : target
        if (el) {
          watch(context.selectedId, id => {
            if (id) el.setAttribute('data-theme', String(id))
          }, { immediate: true })
        }
      }
    }

    update(colors: Record<string, Colors>, isDark?: boolean): void {
      // Get generated CSS from base class
      const css = this.generate(colors, isDark)

      // Custom injection logic
      console.log('Updating theme CSS:', css)
      this.injectStyles(css)
    }

    private injectStyles(css: string): void {
      // Your custom logic here
      const style = document.createElement('style')
      style.textContent = css
      document.head.appendChild(style)
    }
  }
```

The `generate` method from `ThemeAdapter` creates CSS like:

```css
  [data-theme="light"] {
    --my-prefix-primary: #3b82f6;
    --my-prefix-secondary: #8b5cf6;
    --my-prefix-background: #ffffff;
  }

  [data-theme="dark"] {
    --my-prefix-primary: #60a5fa;
    --my-prefix-secondary: #a78bfa;
    --my-prefix-background: #1e293b;
  }

  :root {
    color-scheme: light;
  }
```

Note: The `color-scheme` value updates based on the current theme's `dark` property.

#### Option 2: Implement Interface Directly

For complete control, implement `ThemeAdapterInterface` directly:

```ts
  import { watch, onScopeDispose } from 'vue'
  import type { App } from 'vue'
  import type { ThemeAdapterInterface, ThemeAdapterSetupContext, Colors } from '@vuetify/v0'

  class CustomThemeAdapter implements ThemeAdapterInterface {
    setup<T extends ThemeAdapterSetupContext>(
      app: App,
      context: T,
      target?: string | HTMLElement | null
    ): void {
      // Set up your custom watchers
      const stopWatch = watch(context.colors, colors => {
        this.update(colors)
      }, { immediate: true })

      onScopeDispose(stopWatch, true)
    }

    update(colors: Record<string, Colors>, isDark?: boolean): void {
      // Completely custom implementation
      for (const [themeName, themeColors] of Object.entries(colors)) {
        for (const [colorName, colorValue] of Object.entries(themeColors)) {
          document.documentElement.style.setProperty(
            `--theme-${themeName}-${colorName}`,
            colorValue
          )
        }
      }

      // Optionally handle color-scheme
      if (isDark !== undefined) {
        document.documentElement.style.colorScheme = isDark ? 'dark' : 'light'
      }
    }
  }
```

### Example: TailwindCSS Adapter

Integrate with TailwindCSS using CSS custom properties:

```ts
  class TailwindThemeAdapter implements ThemeAdapterInterface {
    update(colors: Record<string, Colors>): void {
      // Set CSS variables on :root for Tailwind
      const root = document.documentElement

      for (const [themeName, themeColors] of Object.entries(colors)) {
        for (const [colorName, colorValue] of Object.entries(themeColors)) {
          root.style.setProperty(
            `--color-${colorName}`,
            colorValue
          )
        }
      }
    }
  }

  // Use with Tailwind config
  // tailwind.config.js
  module.exports = {
    theme: {
      extend: {
        colors: {
          primary: 'var(--color-primary)',
          secondary: 'var(--color-secondary)',
          // ...
        }
      }
    }
  }
```

### Example: Vue Reactivity Adapter

Use Vue's reactivity system instead of CSS:

```ts
  import { reactive } from 'vue'
  import type { ThemeAdapterInterface, Colors } from '@vuetify/v0'

  class ReactiveThemeAdapter implements ThemeAdapterInterface {
    public themeColors = reactive<Record<string, Colors>>({})

    update(colors: Record<string, Colors>): void {
      // Update reactive object
      Object.assign(this.themeColors, colors)
    }
  }

  // Usage in components
  const adapter = new ReactiveThemeAdapter()

  app.use(createThemePlugin({
    adapter,
    themes: { /* ... */ }
  }))

  // Access in components
  const colors = adapter.themeColors
```

### Example: localStorage Persistence Adapter

Automatically persist theme selection:

```ts
  class PersistentThemeAdapter extends ThemeAdapter {
    private storageKey = 'app-theme'

    constructor() {
      super('v0')
      this.loadPersistedTheme()
    }

    update(colors: Record<string, Colors>): void {
      const css = this.generate(colors)
      this.injectStyles(css)

      // Persist to localStorage
      this.persistTheme(colors)
    }

    private injectStyles(css: string): void {
      let style = document.querySelector('#theme-styles') as HTMLStyleElement
      if (!style) {
        style = document.createElement('style')
        style.id = 'theme-styles'
        document.head.appendChild(style)
      }
      style.textContent = css
    }

    private persistTheme(colors: Record<string, Colors>): void {
      localStorage.setItem(this.storageKey, JSON.stringify(colors))
    }

    private loadPersistedTheme(): void {
      const stored = localStorage.getItem(this.storageKey)
      if (stored) {
        try {
          const colors = JSON.parse(stored)
          this.update(colors)
        } catch (e) {
          console.error('Failed to load persisted theme:', e)
        }
      }
    }
  }
```

### Example: Multiple Output Adapter

Generate CSS for multiple targets:

```ts
  class MultiTargetAdapter extends ThemeAdapter {
    constructor() {
      super('v0')
    }

    update(colors: Record<string, Colors>): void {
      // Generate CSS with different strategies
      this.updateCSSVariables(colors)
      this.updateDataAttributes(colors)
      this.updateClassNames(colors)
    }

    private updateCSSVariables(colors: Record<string, Colors>): void {
      const css = this.generate(colors)
      // Inject as CSS variables
      this.injectToHead(css, 'css-vars')
    }

    private updateDataAttributes(colors: Record<string, Colors>): void {
      // Set data attributes on body
      for (const [theme, themeColors] of Object.entries(colors)) {
        for (const [key, value] of Object.entries(themeColors)) {
          document.body.dataset[`theme${theme}${key}`] = value
        }
      }
    }

    private updateClassNames(colors: Record<string, Colors>): void {
      // Add theme-specific classes
      document.body.className = document.body.className
        .split(' ')
        .filter(c => !c.startsWith('theme-'))
        .concat(Object.keys(colors).map(t => `theme-${t}`))
        .join(' ')
    }

    private injectToHead(css: string, id: string): void {
      let style = document.querySelector(`#${id}`) as HTMLStyleElement
      if (!style) {
        style = document.createElement('style')
        style.id = id
        document.head.appendChild(style)
      }
      style.textContent = css
    }
  }
```

### Using Custom Adapters

Pass your adapter to the theme plugin or context:

```ts
  // With plugin
  app.use(createThemePlugin({
    adapter: new MyThemeAdapter(),
    themes: {
      light: { colors: { primary: '#3b82f6' } },
      dark: { colors: { primary: '#60a5fa' } }
    }
  }))

  // With standalone context
  const [useTheme, provideTheme] = createThemeContext({
    namespace: 'app:theme',
    adapter: new MyThemeAdapter(),
    themes: { /* ... */ }
  })
```

### Adapter Best Practices

1. **Check for browser environment**: Always check if code is running in the browser before DOM manipulation

   ```ts
    import { IN_BROWSER } from '@vuetify/v0'

    update(colors: Record<string, Colors>): void {
      if (!IN_BROWSER) return
      // DOM manipulation here
    }
   ```

2. **Clean up old styles**: Remove old style elements before adding new ones

   ```ts
    const oldStyle = document.querySelector('#my-theme-styles')
    oldStyle?.remove()
   ```

3. **Support CSP nonces**: For Content Security Policy compliance

   ```ts
    constructor(private cspNonce?: string) {}

    update(colors: Record<string, Colors>): void {
      const style = document.createElement('style')
      if (this.cspNonce) {
        style.setAttribute('nonce', this.cspNonce)
      }
      // ...
    }
   ```

4. **Handle errors gracefully**: Don't throw errors that could break the app

   ```ts
    update(colors: Record<string, Colors>): void {
      try {
        this.injectStyles(colors)
      } catch (error) {
        console.error('Theme adapter error:', error)
      }
    }
   ```

5. **Optimize performance**: Batch DOM updates and avoid unnecessary work

   ```ts
    private pendingUpdate: number | null = null

    update(colors: Record<string, Colors>): void {
      if (this.pendingUpdate) {
        cancelAnimationFrame(this.pendingUpdate)
      }
      this.pendingUpdate = requestAnimationFrame(() => {
        this.performUpdate(colors)
      })
    }
   ```

---

# Use Proxy Registry
URL: https://0.vuetifyjs.com/composables/registration/use-proxy-registry

# useProxyRegistry

A reactive proxy wrapper for registry collections that automatically updates refs when items are registered or unregistered.

## Usage

The `useProxyRegistry` composable creates reactive objects that automatically sync with a registry's state. It listens for registry changes and updates the reactive properties accordingly, making it ideal for template-driven UIs that need to react to registry mutations.

**Important:** The registry must have `events: true` enabled for the proxy to receive updates.

```ts
import { useRegistry, useProxyRegistry } from '@vuetify/v0'

const registry = useRegistry({ events: true })
const proxy = useProxyRegistry(registry)

registry.register({ value: 'Item 1' })
registry.register({ value: 'Item 2' })

console.log(proxy.size) // 2
console.log(proxy.keys) // [id1, id2]
```



---

# Use Queue
URL: https://0.vuetifyjs.com/composables/registration/use-queue

# useQueue

A queue composable for managing time-based collections with automatic timeout-based removal, pause/resume functionality, and FIFO (First In, First Out) ordering.

## Usage

The `useQueue` composable provides a powerful interface for managing time-based queues. Built on top of `useRegistry`, it automatically manages timeouts for items, ensuring only the first item in the queue is active at any time. When an item expires or is removed, the next item in the queue automatically becomes active.

```ts
import { useQueue } from '@vuetify/v0'

const queue = useQueue()

const item1 = queue.register({ value: 'First' })
const item2 = queue.register({ value: 'Second' })
const item3 = queue.register({ value: 'Third' })

console.log(item1.isPaused) // false (first item is active)
console.log(item2.isPaused) // true (waiting in queue)
console.log(queue.size) // 3
```



---

# Use Registry
URL: https://0.vuetifyjs.com/composables/registration/use-registry

# useRegistry

A foundational composable for building registration-based systems, managing collections of registered items with automatic indexing, and lifecycle management.

## Usage

The `useRegistry` composable provides a powerful interface for managing collections of items in a registration-based system. It allows you to register, unregister, and look up items efficiently, while maintaining an index for quick access.

```ts
import { useRegistry } from '@vuetify/v0'

const registry = useRegistry()

const ticket1 = registry.register()
const ticket2 = registry.register()
const ticket3 = registry.register()

console.log(registry.size) // 3
```

## Architecture

`useRegistry` is the foundation for specialized registration systems:

```mermaid
flowchart TD
  useRegistry --> useSelection
  useRegistry --> useTokens
  useRegistry --> useForm
  useRegistry --> useQueue
  useRegistry --> useTimeline
```

Each branch extends the base ticket pattern with domain-specific capabilities. See individual composable docs for their extension hierarchies.



---

# Use Timeline
URL: https://0.vuetifyjs.com/composables/registration/use-timeline

# useTimeline

A bounded undo/redo system that manages a fixed-size timeline of registered items with automatic overflow handling and history management.

## Usage

The `useTimeline` composable extends `useRegistry` to provide undo/redo functionality with a bounded history. When the timeline reaches its size limit, older items are moved to an overflow buffer, allowing you to undo back to them while maintaining a fixed active timeline size.

```ts
import { useTimeline } from '@vuetify/v0'

const timeline = useTimeline({ size: 10 })

// Register actions
timeline.register({ id: 'action-1', value: 'Created document' })
timeline.register({ id: 'action-2', value: 'Added title' })
timeline.register({ id: 'action-3', value: 'Added paragraph' })

console.log(timeline.size) // 3

// Undo the last action
timeline.undo()
console.log(timeline.size) // 2

// Redo the undone action
timeline.redo()
console.log(timeline.size) // 3
```



---

# Use Tokens
URL: https://0.vuetifyjs.com/composables/registration/use-tokens

# useTokens

A utility for managing design tokens with support for hierarchical collections, aliases, and token resolution across your application's design system. Inspired by [Design Tokens](https://www.designtokens.org/tr/drafts/format/#design-token).

## Usage

The `useTokens` composable allows you to define a collection of design tokens, which can be primitive values or aliases that reference other tokens. It provides a context for resolving these tokens, making it easy to access design values throughout your application.

```ts
import { useTokens } from '@vuetify/v0'

// Default behavior (depth = Infinity): fully flatten nested objects
const tokens = useTokens({
  color: {
    primary: '#3b82f6',
    secondary: '#64748b',
    info: '{primary}'
  },
  radius: {
    sm: '4px',
    md: '8px',
  },
})

tokens.resolve('color.primary') // '#3b82f6'
tokens.resolve('color.info') // '#3b82f6' (alias resolved)
tokens.resolve('radius.md') // '8px'

const features = useTokens({
  dark: true,
  rtl: { value: true, variation: 'toggle' },
}, { flat: true })

// With flat: true, nested objects are kept as-is at their base id
features.resolve('rtl') // { value: true, variation: 'toggle' }
```

## Architecture

`useTokens` extends `useRegistry` and powers token-based systems:

```mermaid
flowchart TD
  useTokens --> useTheme
  useTokens --> useLocale
  useTokens --> useFeatures
  useTokens --> usePermissions
```



---

# Use Group
URL: https://0.vuetifyjs.com/composables/selection/use-group

# useGroup

The `useGroup` composable is designed to manage a group of related components, allowing for shared state and behavior across them. It supports tri-state (mixed/indeterminate) for checkbox trees and similar use cases where items can be selected, unselected, or in a mixed state.

## Usage

The `useGroup` composable manages a group of selectable items, letting you work with both their IDs and their position indexes.
It supports selecting, unselecting, toggling, and reading the indexes of selected items.

```ts
import { createGroup } from '@vuetify/v0'

// Instantiate group
const group = createGroup()

// Register items
group.register({ id: 'apple', value: 'Apple' })
group.register({ id: 'banana', value: 'Banana' })
group.register({ id: 'cherry', value: 'Cherry' })
group.register({ id: 'date', value: 'Date' })

// Select some items
group.select(['apple', 'banana'])
console.log(group.selectedIndexes.value) // Set { 0, 1 }

// Toggle an item (banana will become unselected)
group.toggle('banana')
console.log(group.selectedIndexes.value) // Set { 0 }

// Unselect apple
group.unselect('apple')
console.log(group.selectedIndexes.value) // Set {}
```

## Tri-State (Mixed/Indeterminate)

Items can be in one of three states: **selected**, **mixed** (indeterminate), or **unselected**. This is useful for checkbox trees where a parent's state depends on its children.

```ts
import { createGroup } from '@vuetify/v0'

const group = createGroup()

group.onboard([
  { id: 'parent', value: 'All Items' },
  { id: 'child-1', value: 'Item 1' },
  { id: 'child-2', value: 'Item 2' },
])

// Set parent to mixed state (some children selected)
group.mix('parent')
console.log(group.mixed('parent')) // true
console.log(group.mixedIds) // Set { 'parent' }

// Selecting clears mixed state
group.select('parent')
console.log(group.mixed('parent')) // false
console.log(group.selectedIds.has('parent')) // true

// Toggle on a mixed item selects it
group.mix('parent')
group.toggle('parent')
console.log(group.selectedIds.has('parent')) // true
```

### Tri-State Checkbox Tree Example

```vue UseGroup
<script setup lang="ts">
  import { createGroup } from '@vuetify/v0'
  import { computed, ref, watchEffect } from 'vue'

  const group = createGroup()

  const parent = group.register({ id: 'parent', value: 'All Items' })
  const children = group.onboard([
    { id: 'child-1', value: 'Item 1' },
    { id: 'child-2', value: 'Item 2' },
    { id: 'child-3', value: 'Item 3' },
  ])

  // Compute parent state based on children
  const allSelected = computed(() => children.every(c => c.isSelected.value))
  const someSelected = computed(() => children.some(c => c.isSelected.value) && !allSelected.value)

  // Sync parent state with children
  watchEffect(() => {
    if (allSelected.value) {
      group.select('parent')
    } else if (someSelected.value) {
      group.mix('parent')
    } else {
      group.unselect('parent')
      group.unmix('parent')
    }
  })

  // Parent checkbox ref for indeterminate property
  const parentCheckbox = ref()
  watchEffect(() => {
    if (parentCheckbox.value) {
      parentCheckbox.value.indeterminate = parent.isMixed.value
    }
  })

  function toggleParent() {
    if (parent.isSelected.value) {
      group.unselect(children.map(c => c.id))
    } else {
      group.select(children.map(c => c.id))
    }
  }
</script>

<template>
  <div>
    <label>
      <input
        ref="parentCheckbox"
        type="checkbox"
        :checked="parent.isSelected.value"
        @change="toggleParent"
      >
      {{ parent.value }}
    </label>

    <div style="margin-left: 1.5rem">
      <label v-for="child in children" :key="child.id">
        <input
          type="checkbox"
          :checked="child.isSelected.value"
          @change="child.toggle()"
        >
        {{ child.value }}
      </label>
    </div>
  </div>
</template>
```

## Select All

For simpler "select all" checkbox patterns, `useGroup` provides context-level helpers that work on all selectable (non-disabled) items at once:

- **`isNoneSelected`**: True when no items are selected
- **`isAllSelected`**: True when all selectable items are selected
- **`isMixed`**: True when some but not all are selected
- **`selectAll()`**: Selects all non-disabled items
- **`unselectAll()`**: Unselects all items (respects mandatory option)
- **`toggleAll()`**: Toggles between all selected and none selected

See the [Group component](/components/group#select-all) for a complete example.



---

# Use Selection
URL: https://0.vuetifyjs.com/composables/selection/use-selection

# useSelection

A composable for managing the selection of items in a collection with automatic indexing and lifecycle management.

## Usage

useSelection extends the functionality of useRegistry to manage selection states for a collection of items. It is reactive, supports both single and multi-select patterns, and provides helper properties for working with selected IDs, values, and items.

```ts
import { useSelection } from '@vuetify/v0'

const selection = useSelection()

selection.register({ id: 'apple', value: 'Apple' })
selection.register({ id: 'banana', value: 'Banana' })

selection.select('apple')
selection.select('banana')

console.log(selection.selectedIds) // Set(2) { 'apple', 'banana' }
console.log(selection.selectedValues) // ComputedRef<Set> { value: Set(2) { 'Apple', 'Banana' } }
console.log(selection.has('apple')) // true
```

## Architecture

`useSelection` extends `useRegistry` and is the base for all selection patterns:

```mermaid
flowchart TD
  useRegistry --> useSelection
  useSelection --> useSingle
  useSelection --> useGroup
  useSingle --> useStep
  useSingle --> useTheme
  useSingle --> useLocale
  useGroup --> useFeatures
```



---

# Use Single
URL: https://0.vuetifyjs.com/composables/selection/use-single

# useSingle

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.

## 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.

```ts
import { useSingle } from '@vuetify/v0'

const single = useSingle()

// 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:

```mermaid
flowchart TD
  useRegistry --> useSelection
  useSelection --> useSingle
```



---

# Use Step
URL: https://0.vuetifyjs.com/composables/selection/use-step

# useStep

A composable for managing navigation through multi-step processes like forms, wizards, or onboarding flows, with support for step tracking, completion, and navigation controls.

## Usage

The `useStep` composable manages a list of steps and allows navigation between them with configurable circular (wrapping) or bounded (stopping at edges) behavior.
You register each step (with an `id` and value) in the order they should be navigated, then use the navigation methods to move

```ts
import { createStep } from '@vuetify/v0'

// Bounded navigation (default) - for wizards, forms
const wizard = createStep({ circular: false })

wizard.onboard([
  { id: 'step1', value: 'Account Info' },
  { id: 'step2', value: 'Payment' },
  { id: 'step3', value: 'Confirmation' },
])

wizard.first()    // Go to step1
wizard.next()     // Go to step2
wizard.next()     // Go to step3
wizard.next()     // Stays at step3 (bounded)

// Circular navigation - for carousels, theme switchers
const carousel = createStep({ circular: true })

carousel.onboard([
  { id: 'slide1', value: 'First' },
  { id: 'slide2', value: 'Second' },
  { id: 'slide3', value: 'Third' },
])

carousel.last()   // Go to slide3
carousel.next()   // Wraps to slide1
carousel.prev()   // Wraps to slide3
```



---

# Use Click Outside
URL: https://0.vuetifyjs.com/composables/system/use-click-outside

<script setup>
import BasicExample from '@/examples/composables/use-click-outside/basic.vue'
import BasicExampleRaw from '@/examples/composables/use-click-outside/basic.vue?raw'
</script>

# useClickOutside

A composable for detecting clicks outside of specified element(s) with automatic cleanup.

## Usage

The `useClickOutside` composable detects when users click outside target elements. It uses two-phase detection (pointerdown → pointerup) to prevent false positives when dragging, and includes touch scroll handling for mobile.

## Examples

### With Component Refs

When using component refs (like Atom), pass a getter that returns the exposed element:

```ts
import { Atom, useClickOutside } from '@vuetify/v0'
import { ref, useTemplateRef } from 'vue'

const isOpen = ref(true)
const popoverRef = useTemplateRef<AtomExpose>('popover')

useClickOutside(
  () => popoverRef.value?.element,
  () => { isOpen.value = false }
)
```

### Multiple Targets

Detect clicks outside multiple elements (e.g., anchor and popover):

```ts
import { useClickOutside } from '@vuetify/v0'
import { ref, useTemplateRef } from 'vue'

const isOpen = ref(false)
const anchorRef = useTemplateRef<HTMLElement>('anchor')
const popoverRef = useTemplateRef<AtomExpose>('popover')

useClickOutside(
  [anchorRef, () => popoverRef.value?.element],
  () => { isOpen.value = false }
)
```

### Ignoring Elements

Ignore specific elements via CSS selectors or refs:

```ts
import { useClickOutside } from '@vuetify/v0'
import { useTemplateRef } from 'vue'

const menuRef = useTemplateRef<HTMLElement>('menu')

useClickOutside(menuRef, close, {
  ignore: ['[data-app-bar]', '.toast-container']
})
```

### Pause and Resume

Control detection programmatically:

```ts
const { pause, resume, stop, isPaused } = useClickOutside(menuRef, close)

// Temporarily disable during animations
pause()

// Re-enable after animation
resume()

// Permanently stop and cleanup
stop()
```

## Accessibility

This composable handles pointer interactions only. For accessible overlays, you **must** implement additional patterns.

### Keyboard Dismissal (Required)

> **WCAG 2.1.2 Level A**: Without keyboard dismissal, click-outside creates a keyboard trap. This is a compliance failure.

```ts
import { useClickOutside, useKeydown } from '@vuetify/v0'

// Pointer dismissal
useClickOutside(menuRef, close)

// Keyboard dismissal - REQUIRED for WCAG 2.1.2
useKeydown({ key: 'Escape', handler: close })
```

### Focus Restoration

Return focus to the trigger element after dismissal per APG dialog patterns:

```ts
import { nextTick } from 'vue'

function close() {
  isOpen.value = false
  // Return focus to trigger for screen reader context
  nextTick(() => buttonRef.value?.focus())
}

useClickOutside(menuRef, close)
```

### Mobile Screen Reader Support

Mobile screen reader users (VoiceOver, TalkBack) cannot press Escape. Include a focusable close button within overlays:

```vue
<div ref="menu" role="menu">
  <!-- Visually hidden close for screen readers -->
  <button class="sr-only" @click="close" aria-label="Close menu">
    Close
  </button>
  <!-- menu items -->
</div>
```

The `sr-only` class hides content visually while keeping it accessible:

```css
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}
```



---

# Use Event Listener
URL: https://0.vuetifyjs.com/composables/system/use-event-listener

# useEventListener

A composable for handling DOM events with automatic cleanup on component unmount.

## Usage

The `useEventListener` composable attaches event listeners to DOM elements (Window, Document, or HTMLElement) with automatic cleanup when the component is unmounted. It supports reactive targets, multiple events, and multiple handlers.

```vue UseEventListener
<script setup lang="ts">
  import { useEventListener, useWindowEventListener, useDocumentEventListener } from '@vuetify/v0'
  import { ref, useTemplateRef } from 'vue'

  // Track window dimensions
  const windowSize = ref({ width: window.innerWidth, height: window.innerHeight })
  useWindowEventListener('resize', () => {
    windowSize.value = {
      width: window.innerWidth,
      height: window.innerHeight
    }
  })

  // Handle keyboard shortcuts
  useDocumentEventListener('keydown', (e) => {
    if (e.ctrlKey && e.key === 's') {
      e.preventDefault()
      console.log('Save shortcut triggered')
    }
  })

  // Element-specific listener
  const button = useTemplateRef('button')
  useEventListener(button, 'click', () => {
    console.log('Button clicked!')
  })
</script>

<template>
  <div>
    <p>Window: {{ windowSize.width }}x{{ windowSize.height }}</p>
    <button ref="button">Click me</button>
  </div>
</template>
```

## Lifecycle & Cleanup

### Automatic Cleanup

`useEventListener` automatically removes event listeners when:
- The component unmounts
- The Vue effect scope is disposed
- You manually call the returned `stop()` function

**Implementation:**
```ts
// Uses Vue's onScopeDispose internally
onScopeDispose(stop, true)
```

This ensures no memory leaks even if you forget to manually cleanup.

### Manual Cleanup

```ts
const stop = useEventListener(element, 'click', handler)

// Later, manually cleanup if needed
stop()
```

### Reactive Listeners

`useEventListener` supports **reactive** targets, events, and listeners. When any reactive dependency changes, listeners are automatically re-registered:

```ts
const target = ref<HTMLElement | null>(null)
const eventName = ref<string>('click')

// Automatically updates when refs change
useEventListener(target, eventName, () => {
  console.log('Event fired!')
})

// Later - listener automatically re-registers with new event
eventName.value = 'dblclick'
```

**Implementation Details:**

Uses Vue's `watch` with specific options:

```ts
watch(
  () => [toValue(target), toValue(event), unref(listener), toValue(options)],
  handler,
  { immediate: true, flush: 'post' }
)
```

- **`immediate: true`** - Registers listeners immediately on mount
- **`flush: 'post'`** - Waits for DOM updates before registering (important for template refs)
- **`watch` vs `watchEffect`** - Explicit dependencies for better performance

### Template Refs

Works seamlessly with Vue's `useTemplateRef`:

```vue UseEventListener
<script setup lang="ts">
  import { useTemplateRef } from 'vue'
  import { useEventListener } from '@vuetify/v0'

  const button = useTemplateRef('btn')

  // Waits for template ref to be available (flush: 'post')
  useEventListener(button, 'click', () => {
    console.log('Button clicked')
  })
</script>

<template>
  <button ref="btn">Click me</button>
</template>
```

### Usage Outside Components

If you call `useEventListener` outside a component setup function:
- **No automatic cleanup** (no active effect scope)
- **Must manually call** the returned `stop()` function
- Consider wrapping in `effectScope()` for proper cleanup

```ts
import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  useEventListener(window, 'resize', handler)
})

// Later, dispose the entire scope
scope.stop()
```

### SSR Considerations

Event listeners are only attached when code runs in the browser. The composable checks for browser environment internally, so no special handling is needed for SSR.

### Multiple Events & Handlers

You can listen to multiple events or use multiple handlers:

```ts
// Multiple events
useEventListener(element, ['click', 'dblclick'], handler)

// Multiple handlers
useEventListener(element, 'click', [handler1, handler2])

// Both
useEventListener(element, ['click', 'dblclick'], [handler1, handler2])
```

All combinations are automatically managed and cleaned up together.

---

# Use Intersection Observer
URL: https://0.vuetifyjs.com/composables/system/use-intersection-observer

# useIntersectionObserver

A composable for detecting when elements enter or leave the viewport using the Intersection Observer API with automatic cleanup.

## Usage

The `useIntersectionObserver` composable wraps the Intersection Observer API to detect when elements become visible in the viewport. It's useful for lazy loading images, infinite scroll, entrance animations, and performance optimizations.

```vue UseIntersectionObserver
<script setup lang="ts">
  import { useIntersectionObserver } from '@vuetify/v0'
  import { ref, useTemplateRef } from 'vue'

  const target = useTemplateRef('target')
  const isVisible = ref(false)

  useIntersectionObserver(target, (entries) => {
    isVisible.value = entries[0].isIntersecting
  }, {
    threshold: 0.5, // Trigger when 50% visible
    rootMargin: '0px'
  })
</script>

<template>
  <div>
    <div style="height: 100vh">Scroll down to see the element</div>
    <div ref="target" :class="{ visible: isVisible }">
      I'm {{ isVisible ? 'visible' : 'hidden' }}
    </div>
  </div>
</template>
```

## Lifecycle & Cleanup

### Automatic Cleanup

`useIntersectionObserver` automatically disconnects the observer when:
- The component unmounts
- The Vue effect scope is disposed
- You call the returned `stop()` function

**Implementation:**
```ts
// Uses Vue's onScopeDispose internally
onScopeDispose(() => observer.disconnect())
```

This prevents memory leaks by ensuring observers don't continue running after the component is destroyed.

### Manual Control

The composable returns control functions for fine-grained lifecycle management:

```ts
const { isActive, isIntersecting, pause, resume, stop } = useIntersectionObserver(
  element,
  callback
)

// Check if observer is active
console.log(isActive.value) // true

// Temporarily pause observation (keeps observer alive)
pause()
console.log(isActive.value) // false
console.log(isIntersecting.value) // false (reset on pause)

// Resume observation
resume()
console.log(isActive.value) // true

// Permanently stop and disconnect observer
stop()
console.log(isActive.value) // false
```

**State properties:**
- **`isActive`**: True when the observer exists and is observing (false when paused or stopped)
- **`isPaused`**: True when observation is temporarily paused
- **`isIntersecting`**: True when the element is currently intersecting the viewport

**Difference between pause and stop:**
- **`pause()`**: Temporarily stops observing, can be resumed with `resume()`
- **`stop()`**: Permanently disconnects the observer, cannot be restarted

### Reactive Target

The target element can be reactive. When the target ref changes, the observer automatically re-attaches:

```ts
const element = ref<HTMLElement | null>(null)

useIntersectionObserver(element, callback)

// Later - observer automatically reconnects to new element
element.value = document.querySelector('.new-target')
```

### Template Refs

Works seamlessly with Vue's template refs:

```vue UseIntersectionObserver
<script setup lang="ts">
  import { useTemplateRef } from 'vue'
  import { useIntersectionObserver } from '@vuetify/v0'

  const section = useTemplateRef('section')

  const { isIntersecting } = useIntersectionObserver(
    section,
    ([entry]) => {
      console.log('Section visibility:', entry.isIntersecting)
    }
  )
</script>

<template>
  <section ref="section">
    <p v-if="isIntersecting">Now visible!</p>
  </section>
</template>
```

### Usage Outside Components

If called outside a component setup function:
- **No automatic cleanup** (no active effect scope)
- **Must manually call** `stop()` to prevent memory leaks
- Consider wrapping in `effectScope()`:

```ts
import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  useIntersectionObserver(element, callback)
})

// Later, cleanup all observers in the scope
scope.stop()
```

### SSR Considerations

`IntersectionObserver` is a browser-only API. The composable checks for browser environment internally:

```ts
// Safe to call during SSR - will not throw
const { isIntersecting } = useIntersectionObserver(element, callback)
// isIntersecting.value will be false in SSR
```

### Performance Tips

**Use appropriate thresholds:**
```ts
// Trigger once when element appears
useIntersectionObserver(element, callback, { threshold: 0 })

// Trigger at multiple visibility levels
useIntersectionObserver(element, callback, { threshold: [0, 0.25, 0.5, 0.75, 1] })
```

**Use rootMargin for early loading:**
```ts
// Start loading 200px before element enters viewport
useIntersectionObserver(element, callback, {
  rootMargin: '200px'
})
```

**Pause when not needed:**
```ts
const { pause, resume } = useIntersectionObserver(element, callback)

// Pause during heavy operations
pause()
performHeavyWork()
resume()
```

---

# Use Keydown
URL: https://0.vuetifyjs.com/composables/system/use-keydown

# useKeydown

A composable for handling keyboard events with automatic cleanup and customizable behavior.

## Usage

The `useKeydown` composable registers keyboard event handlers on the document with automatic cleanup when the component is unmounted. It supports multiple key handlers, preventDefault, and stopPropagation options.

```vue UseKeydown
<script setup lang="ts">
  import { useKeydown } from '@vuetify/v0'
  import { ref } from 'vue'

  const modalOpen = ref(false)
  const searchQuery = ref('')

  // Handle Escape key to close modal
  useKeydown({
    key: 'Escape',
    handler: () => {
      modalOpen.value = false
    },
    preventDefault: true
  })

  // Handle Ctrl+K for search
  useKeydown({
    key: 'k',
    handler: (event) => {
      if (event.ctrlKey || event.metaKey) {
        modalOpen.value = true
        searchQuery.value = ''
      }
    },
    preventDefault: true
  })

  // Handle Arrow keys for navigation
  useKeydown([
    {
      key: 'ArrowUp',
      handler: () => navigatePrevious(),
      preventDefault: true
    },
    {
      key: 'ArrowDown',
      handler: () => navigateNext(),
      preventDefault: true
    }
  ])
</script>

<template>
  <div>
    <p>Press Escape to close, Ctrl+K to search</p>
    <div v-if="modalOpen">Modal is open</div>
  </div>
</template>
```



---

# Use Mutation Observer
URL: https://0.vuetifyjs.com/composables/system/use-mutation-observer

# useMutationObserver

A composable for detecting DOM changes using the Mutation Observer API with automatic cleanup.

## Usage

The `useMutationObserver` composable wraps the Mutation Observer API to detect changes to the DOM tree. It's useful for monitoring attribute changes, child element modifications, and character data updates.

```vue UseMutationObserver
<script setup lang="ts">
  import { useMutationObserver } from '@vuetify/v0'
  import { ref, useTemplateRef } from 'vue'

  const target = useTemplateRef('target')
  const mutationCount = ref(0)

  useMutationObserver(target, (mutations) => {
    mutationCount.value += mutations.length
    mutations.forEach(mutation => {
      console.log('Type:', mutation.type)
      console.log('Added nodes:', mutation.addedNodes)
      console.log('Removed nodes:', mutation.removedNodes)
    })
  }, {
    childList: true,
    attributes: true,
    attributeOldValue: true
  })
</script>

<template>
  <div>
    <div ref="target">
      <p>Mutations detected: {{ mutationCount }}</p>
    </div>
  </div>
</template>
```

## Lifecycle & Cleanup

### Automatic Cleanup

`useMutationObserver` automatically disconnects the observer when:
- The component unmounts
- The Vue effect scope is disposed
- You call the returned `stop()` function

**Implementation:**
```ts
// Uses Vue's onScopeDispose internally
onScopeDispose(() => observer.disconnect())
```

This prevents memory leaks by ensuring observers don't continue running after the component is destroyed.

### Manual Control

The composable returns control functions for fine-grained lifecycle management:

```ts
const { isActive, isPaused, pause, resume, stop } = useMutationObserver(
  element,
  callback,
  options
)

// Check if observer is active
console.log(isActive.value) // true

// Temporarily pause observation (keeps observer alive)
pause()
console.log(isActive.value) // false

// Resume observation
resume()
console.log(isActive.value) // true

// Permanently stop and disconnect observer
stop()
console.log(isActive.value) // false
```

**State properties:**
- **`isActive`**: True when the observer exists and is observing (false when paused or stopped)
- **`isPaused`**: True when observation is temporarily paused

**Difference between pause and stop:**
- **`pause()`**: Temporarily stops observing, can be resumed with `resume()`
- **`stop()`**: Permanently disconnects the observer, cannot be restarted

### Reactive Target

The target element can be reactive. When the target ref changes, the observer automatically re-attaches:

```ts
const element = ref<HTMLElement | null>(null)

useMutationObserver(element, callback, options)

// Later - observer automatically reconnects to new element
element.value = document.querySelector('.new-target')
```

### Template Refs

Works seamlessly with Vue's template refs:

```vue UseMutationObserver
<script setup lang="ts">
  import { useTemplateRef } from 'vue'
  import { useMutationObserver } from '@vuetify/v0'

  const content = useTemplateRef('content')

  useMutationObserver(
    content,
    (mutations) => {
      console.log('DOM changed:', mutations.length, 'mutations')
    },
    {
      childList: true,
      subtree: true
    }
  )
</script>

<template>
  <div ref="content">
    <!-- Mutations will be observed here -->
  </div>
</template>
```

### Usage Outside Components

If called outside a component setup function:
- **No automatic cleanup** (no active effect scope)
- **Must manually call** `stop()` to prevent memory leaks
- Consider wrapping in `effectScope()`:

```ts
import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  useMutationObserver(element, callback, options)
})

// Later, cleanup all observers in the scope
scope.stop()
```

### SSR Considerations

`MutationObserver` is a browser-only API. The composable checks for browser environment internally:

```ts
// Safe to call during SSR - will not throw
const { isActive, isPaused } = useMutationObserver(element, callback, options)
// isActive.value and isPaused.value will be false in SSR
```

### Performance Tips

**Observe only what you need:**
```ts
// Instead of observing everything
useMutationObserver(element, callback, {
  childList: true,
  attributes: true,
  characterData: true,
  subtree: true // Expensive!
})

// Be specific
useMutationObserver(element, callback, {
  attributes: true,
  attributeFilter: ['class', 'style'] // Only these attributes
})
```

**Use subtree sparingly:**
```ts
// Observing subtree on large DOM can be expensive
useMutationObserver(element, callback, {
  subtree: true, // Watches all descendants
  childList: true
})

// Consider observing specific child elements instead
const child = ref(element.value?.querySelector('.specific-child'))
useMutationObserver(child, callback, { childList: true })
```

**Debounce frequent mutations:**
```ts
import { debounce } from 'lodash-es'

const debouncedCallback = debounce((mutations: MutationRecord[]) => {
  console.log('Mutations:', mutations)
}, 100)

useMutationObserver(element, debouncedCallback, {
  childList: true,
  subtree: true
})
```

**Pause during heavy operations:**
```ts
const { pause, resume } = useMutationObserver(element, callback, options)

// Pause during bulk DOM updates
pause()
performBulkDOMUpdates()
resume()
```

---

# Use Resize Observer
URL: https://0.vuetifyjs.com/composables/system/use-resize-observer

# useResizeObserver

A composable for detecting element size changes using the Resize Observer API with automatic cleanup.

## Usage

The `useResizeObserver` composable wraps the Resize Observer API to detect when an element's dimensions change. It's useful for responsive components, charts, virtualized lists, and aspect ratio maintenance.

```vue UseResizeObserver
<script setup lang="ts">
  import { useResizeObserver } from '@vuetify/v0'
  import { ref, useTemplateRef } from 'vue'

  const container = useTemplateRef('container')
  const width = ref(0)
  const height = ref(0)

  useResizeObserver(container, (entries) => {
    const entry = entries[0]
    width.value = entry.contentRect.width
    height.value = entry.contentRect.height
  })
</script>

<template>
  <div ref="container" class="resizable">
    <p>Width: {{ width }}px</p>
    <p>Height: {{ height }}px</p>
  </div>
</template>
```

## Lifecycle & Cleanup

### Automatic Cleanup

`useResizeObserver` automatically disconnects the observer when:
- The component unmounts
- The Vue effect scope is disposed
- You call the returned `stop()` function

**Implementation:**
```ts
// Uses Vue's onScopeDispose internally
onScopeDispose(() => observer.disconnect())
```

This prevents memory leaks by ensuring observers don't continue running after the component is destroyed.

### Manual Control

The composable returns control functions for fine-grained lifecycle management:

```ts
const { isActive, isPaused, pause, resume, stop } = useResizeObserver(
  element,
  callback,
  options
)

// Check if observer is active
console.log(isActive.value) // true

// Temporarily pause observation (keeps observer alive)
pause()
console.log(isActive.value) // false

// Resume observation
resume()
console.log(isActive.value) // true

// Permanently stop and disconnect observer
stop()
console.log(isActive.value) // false
```

**State properties:**
- **`isActive`**: True when the observer exists and is observing (false when paused or stopped)
- **`isPaused`**: True when observation is temporarily paused

**Difference between pause and stop:**
- **`pause()`**: Temporarily stops observing, can be resumed with `resume()`
- **`stop()`**: Permanently disconnects the observer, cannot be restarted

### Reactive Target

The target element can be reactive. When the target ref changes, the observer automatically re-attaches:

```ts
const element = ref<HTMLElement | null>(null)

useResizeObserver(element, callback, options)

// Later - observer automatically reconnects to new element
element.value = document.querySelector('.new-target')
```

### Template Refs

Works seamlessly with Vue's template refs:

```vue UseResizeObserver
<script setup lang="ts">
  import { useTemplateRef } from 'vue'
  import { useResizeObserver } from '@vuetify/v0'

  const panel = useTemplateRef('panel')

  useResizeObserver(
    panel,
    ([entry]) => {
      const { width, height } = entry.contentRect
      console.log('Panel resized:', width, 'x', height)
    }
  )
</script>

<template>
  <div ref="panel" class="resizable-panel">
    <!-- Size changes will be observed -->
  </div>
</template>
```

### Usage Outside Components

If called outside a component setup function:
- **No automatic cleanup** (no active effect scope)
- **Must manually call** `stop()` to prevent memory leaks
- Consider wrapping in `effectScope()`:

```ts
import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  useResizeObserver(element, callback, options)
})

// Later, cleanup all observers in the scope
scope.stop()
```

### SSR Considerations

`ResizeObserver` is a browser-only API. The composable checks for browser environment internally:

```ts
// Safe to call during SSR - will not throw
const { isActive, isPaused } = useResizeObserver(element, callback, options)
// isActive.value and isPaused.value will be false in SSR

// useElementSize also handles SSR safely
const { width, height, isActive } = useElementSize(element)
// width.value and height.value will be 0 in SSR
// isActive.value will be false in SSR
```

### Performance Tips

**Use debouncing for expensive operations:**
```ts
import { debounce } from 'lodash-es'

const debouncedCallback = debounce((entries: ResizeObserverEntry[]) => {
  const { width, height } = entries[0].contentRect
  expensiveLayoutCalculation(width, height)
}, 150)

useResizeObserver(element, debouncedCallback)
```

**Pause during animations:**
```ts
const { pause, resume } = useResizeObserver(element, callback)

// Pause during CSS animations to avoid callback spam
element.value?.classList.add('animating')
pause()
await animationComplete()
resume()
element.value?.classList.remove('animating')
```

**Choose the right box model:**
```ts
// content-box - excludes padding and border (default)
useResizeObserver(element, callback, { box: 'content-box' })

// border-box - includes padding and border
useResizeObserver(element, callback, { box: 'border-box' })
```

**Batch multiple observations:**
```ts
// Instead of multiple observers
const elements = [el1, el2, el3]
elements.forEach(el => {
  useResizeObserver(el, callback) // Creates 3 observers
})

// Use a single observer with multiple elements
const observer = new ResizeObserver(callback)
elements.forEach(el => observer.observe(el.value))
onScopeDispose(() => observer.disconnect())
```

### Common Use Cases

**Responsive Charts:**
```ts
const chart = useTemplateRef('chart')
const { width, height } = useElementSize(chart, { immediate: true })

watch([width, height], ([w, h]) => {
  chartInstance.resize(w, h)
})
```

**Container Queries Alternative:**
```ts
const container = useTemplateRef('container')
const containerClass = ref('container-sm')

useResizeObserver(container, ([entry]) => {
  const width = entry.contentRect.width
  if (width < 600) containerClass.value = 'container-sm'
  else if (width < 1200) containerClass.value = 'container-md'
  else containerClass.value = 'container-lg'
})
```

**Virtualized Lists:**
```ts
const list = useTemplateRef('list')
const { height } = useElementSize(list)

const visibleItems = computed(() => {
  const itemHeight = 40
  return Math.ceil(height.value / itemHeight)
})
```

---

# Use Toggle Scope
URL: https://0.vuetifyjs.com/composables/system/use-toggle-scope

# useToggleScope

A composable for conditionally managing Vue effect scopes based on reactive boolean conditions with automatic cleanup.

## Usage

The `useToggleScope` composable wraps Vue's `effectScope` API to create and destroy reactive effect scopes based on a boolean condition. When the condition becomes true, a new scope is created and your callback runs. When false, the scope is stopped and all effects are cleaned up automatically.

```vue UseToggleScope
<script setup lang="ts">
  import { useToggleScope } from '@vuetify/v0'
  import { shallowRef, watch } from 'vue'

  const isEnabled = shallowRef(false)
  const data = shallowRef(0)

  const { isActive } = useToggleScope(isEnabled, () => {
    // This watch is only active when isEnabled is true
    watch(data, (value) => {
      console.log('Data changed:', value)
    })
  })
</script>

<template>
  <div>
    <button @click="isEnabled = !isEnabled">
      {{ isEnabled ? 'Disable' : 'Enable' }} Watcher
    </button>
    <p>Scope active: {{ isActive }}</p>
    <input v-model.number="data" type="number">
  </div>
</template>
```

### `useToggleScope`

- **Type**
  ```ts
  interface ToggleScopeControls {
    isActive: Readonly<Ref<boolean>>
    stop: () => void
    start: () => void
    reset: () => void
  }

  function useToggleScope(
    source: WatchSource<boolean>,
    fn: (() => void) | ((controls: ToggleScopeControls) => void)
  ): ToggleScopeControls
  ```

- **Details**

  Creates an effect scope that is conditionally active based on a reactive boolean source. All reactive effects created within the scope are automatically cleaned up when the scope stops.

- **Parameters**

  - `source`: A reactive boolean value or getter that controls when the scope is active
  - `fn`: Function to execute within the scope. Can optionally receive controls for manual scope management.

- **Returns**

  - `isActive`: Whether the scope is currently active (created and running)
  - `stop()`: Stop the scope (destroys and cleans up all effects)
  - `start()`: Start the scope (creates and runs effects)
  - `reset()`: Reset the scope (stops and immediately restarts)

- **Example**
  ```ts
  const isFeatureEnabled = ref(false)

  const { isActive, stop, start } = useToggleScope(isFeatureEnabled, () => {
    // All watchers and effects created here are automatically cleaned up
    // when isFeatureEnabled becomes false

    watch(someData, () => {
      console.log('Data changed')
    })

    watchEffect(() => {
      console.log('Effect running')
    })
  })

  // Manually control the scope
  stop()  // Stops even if isFeatureEnabled is true
  start() // Starts the scope
  ```

## Use Cases

### Feature Flags

Enable/disable features dynamically with proper cleanup:

```ts
const isDarkMode = shallowRef(false)

useToggleScope(isDarkMode, () => {
  // Dark mode specific watchers and effects
  watch(theme, (value) => {
    document.documentElement.classList.toggle('dark', value.isDark)
  })

  // Auto-cleanup when dark mode is disabled
})
```

### Conditional API Polling

Start/stop polling based on component visibility:

```ts
const isVisible = shallowRef(true)

useToggleScope(isVisible, () => {
  const intervalId = setInterval(() => {
    fetchData()
  }, 5000)

  onScopeDispose(() => {
    clearInterval(intervalId)
  })
})
```

### Performance Optimization

Only run expensive reactive effects when needed:

```ts
const isExpanded = shallowRef(false)

useToggleScope(isExpanded, () => {
  // Heavy computations only run when panel is expanded
  watch([data1, data2, data3], () => {
    performExpensiveCalculation()
  })
})
```

### Debug Mode

Toggle debug logging without performance overhead:

```ts
const isDebugMode = shallowRef(false)

useToggleScope(isDebugMode, () => {
  watch(() => store.state, (state) => {
    console.log('State changed:', state)
  }, { deep: true })
})
```

## Lifecycle & Cleanup

### Automatic Cleanup

`useToggleScope` automatically cleans up the effect scope when:
- The source condition becomes false
- The parent component unmounts
- The parent Vue effect scope is disposed

**Implementation:**
```ts
// All effects are disposed when scope stops
scope.value?.stop()
```

This ensures all watchers, computed properties, and effects created within the scope are properly cleaned up, preventing memory leaks.

### Manual Control

The composable returns control functions for manual scope management:

```ts
const { isActive, start, stop, reset } = useToggleScope(isEnabled, () => {
  // Scope logic
})

// Check if scope is active
console.log(isActive.value) // true/false

// Manually stop the scope
stop()

// Manually start the scope
start()

// Reset (stop and immediately restart)
reset()
```

### Using Controls Inside Scope

Pass controls to the scope function for self-management:

```ts
useToggleScope(isEnabled, (controls) => {
  // Access scope state
  console.log('Active:', controls.isActive.value)

  // Self-reset on certain conditions
  watch(errorCount, (count) => {
    if (count > 10) {
      controls.reset() // Restart the scope
    }
  })
})
```

## Advanced Patterns

### Nested Scopes

Create hierarchical scope management:

```ts
const parentEnabled = shallowRef(true)
const childEnabled = shallowRef(true)

useToggleScope(parentEnabled, () => {
  console.log('Parent scope active')

  useToggleScope(childEnabled, () => {
    console.log('Child scope active')
    // Child automatically stops when parent stops
  })
})
```

### Coordinated Scopes

Multiple scopes controlled by different conditions:

```ts
const isOnline = shallowRef(true)
const isAuthenticated = shallowRef(false)

// API polling only when online
useToggleScope(isOnline, () => {
  setInterval(() => fetchData(), 5000)
})

// User-specific features only when authenticated
useToggleScope(isAuthenticated, () => {
  watch(userData, syncToServer)
})
```

### Delayed Activation

Use computed source for complex conditions:

```ts
const isReady = shallowRef(false)
const hasData = shallowRef(false)
const shouldActivate = computed(() => isReady.value && hasData.value)

useToggleScope(shouldActivate, () => {
  // Only runs when both conditions are true
})
```

### Scope with Cleanup Handler

Ensure proper resource cleanup:

```ts
useToggleScope(isActive, () => {
  const ws = new WebSocket('wss://api.example.com')

  ws.onmessage = (event) => {
    handleMessage(event.data)
  }

  onScopeDispose(() => {
    ws.close()
    console.log('WebSocket closed')
  })
})
```

## Best Practices

**Keep scope functions pure:**
```ts
// Good - self-contained
useToggleScope(isEnabled, () => {
  const data = shallowRef(0)
  watch(data, () => console.log(data.value))
})

// Avoid - external state modifications
let externalCount = 0
useToggleScope(isEnabled, () => {
  externalCount++ // Don't mutate external state
})
```

**Use onScopeDispose for cleanup:**
```ts
useToggleScope(isActive, () => {
  const timerId = setInterval(() => {}, 1000)

  // Always cleanup non-reactive resources
  onScopeDispose(() => {
    clearInterval(timerId)
  })
})
```

**Prefer reactive sources over manual control:**
```ts
// Good - reactive and automatic
const isEnabled = shallowRef(true)
useToggleScope(isEnabled, () => {})

// Less ideal - manual control
const { start, stop } = useToggleScope(() => false, () => {})
start() // Manual management required
```

**Don't create scopes in loops:**
```ts
// Bad - creates multiple scopes
items.forEach(item => {
  useToggleScope(item.isActive, () => {})
})

// Good - single scope observing array
useToggleScope(hasActiveItems, () => {
  items.value.forEach(item => {
    if (item.isActive) setupItem(item)
  })
})
```

## Performance Tips

**Use for expensive operations only:**
```ts
// Good - heavy operation worth toggling
useToggleScope(isExpanded, () => {
  watch(massiveArray, computeExpensiveStats, { deep: true })
})

// Overkill - simple operation
useToggleScope(isVisible, () => {
  const simple = computed(() => a.value + b.value)
})
```

**Batch related effects:**
```ts
// Good - related effects in one scope
useToggleScope(isActive, () => {
  watch(data1, handler1)
  watch(data2, handler2)
  watch(data3, handler3)
})

// Less efficient - separate scopes
useToggleScope(isActive, () => watch(data1, handler1))
useToggleScope(isActive, () => watch(data2, handler2))
useToggleScope(isActive, () => watch(data3, handler3))
```

**Debounce rapid toggles:**
```ts
import { refDebounced } from '@vueuse/core'

const isEnabled = shallowRef(false)
const debouncedEnabled = refDebounced(isEnabled, 300)

useToggleScope(debouncedEnabled, () => {
  // Won't thrash on rapid toggles
})
```

---

# To Array
URL: https://0.vuetifyjs.com/composables/transformers/to-array

# toArray

The `toArray` utility function provides a consistent way to convert any value into an array format. It handles edge cases like `null` and `undefined` values, and ensures that the output is always an array.

## Usage

```ts
import { toArray } from '@vuetify/v0'

const value = 'Example Value'
const valueAsArray = toArray(value)

console.log(valueAsArray) // ['Example Value']
```



---

# To Reactive
URL: https://0.vuetifyjs.com/composables/transformers/to-reactive

# toReactive

The `toReactive` utility function converts a `MaybeRef` object to a reactive proxy, automatically unwrapping ref values. It provides special handling for `Map`, `Set`, and regular objects.

## Usage

```ts
import { ref } from 'vue'
import { toReactive } from '@vuetify/v0'

const state = ref({ name: 'John', age: 30 })
const rstate = toReactive(state)

console.log(rstate.name) // 'John' (no .value needed)
```



---

# Use Filter
URL: https://0.vuetifyjs.com/composables/utilities/use-filter

# useFilter

A composable for filtering arrays of items based on search queries, supporting both primitive values and complex objects with customizable filtering logic.

## Usage

The `useFilter` composable provides reactive array filtering with multiple modes for different search behaviors. It works with both primitive values and complex objects, and supports filtering by specific keys.

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const items = ref([
  { name: 'John Doe', age: 30, city: 'New York' },
  { name: 'Jane Doe', age: 25, city: 'Los Angeles' },
  { name: 'Peter Jones', age: 40, city: 'Chicago' },
])

const query = ref('doe')
const { items: filtered } = useFilter(query, items, { keys: ['name'] })

console.log(filtered.value)
// [
//   { name: 'John Doe', age: 30, city: 'New York' },
//   { name: 'Jane Doe', age: 25, city: 'Los Angeles' }
// ]
```

## Examples

### Basic String Search

Filter an array of objects by a search term:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const users = ref([
  { id: 1, name: 'Alice Smith', role: 'Admin' },
  { id: 2, name: 'Bob Jones', role: 'User' },
  { id: 3, name: 'Charlie Smith', role: 'User' },
])

const searchQuery = ref('smith')
const { items: filteredUsers } = useFilter(searchQuery, users, {
  keys: ['name']
})

console.log(filteredUsers.value)
// [
//   { id: 1, name: 'Alice Smith', role: 'Admin' },
//   { id: 3, name: 'Charlie Smith', role: 'User' }
// ]
```

### Filtering Primitives

Filter an array of primitive values:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const fruits = ref(['apple', 'banana', 'cherry', 'apricot', 'blueberry'])

const query = ref('ap')
const { items: filtered } = useFilter(query, fruits)

console.log(filtered.value)
// ['apple', 'apricot']
```

### Mode: Some (Default)

Match items where ANY field contains the query:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const products = ref([
  { name: 'Laptop', category: 'Electronics', price: 999 },
  { name: 'Phone', category: 'Electronics', price: 599 },
  { name: 'Desk', category: 'Furniture', price: 299 },
])

const query = ref('electronics')
const { items: filtered } = useFilter(query, products, { mode: 'some' })

console.log(filtered.value)
// [
//   { name: 'Laptop', category: 'Electronics', price: 999 },
//   { name: 'Phone', category: 'Electronics', price: 599 }
// ]
```

### Mode: Every

Match items where ALL fields contain the query:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const items = ref([
  { title: 'Vue Guide', tags: 'vue, guide, tutorial' },
  { title: 'React Guide', tags: 'react, guide' },
  { title: 'Vue API', tags: 'vue, api, reference' },
])

const query = ref('vue')
const { items: filtered } = useFilter(query, items, { mode: 'every' })

console.log(filtered.value)
// [
//   { title: 'Vue Guide', tags: 'vue, guide, tutorial' },
//   { title: 'Vue API', tags: 'vue, api, reference' }
// ]
```

### Mode: Union (OR Logic)

Match items where ANY query matches ANY field:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const books = ref([
  { title: 'JavaScript Basics', author: 'John Doe' },
  { title: 'Vue.js Guide', author: 'Jane Smith' },
  { title: 'TypeScript Deep Dive', author: 'John Smith' },
])

// Search for items containing 'vue' OR 'john'
const queries = ref(['vue', 'john'])
const { items: filtered } = useFilter(queries, books, { mode: 'union' })

console.log(filtered.value)
// [
//   { title: 'JavaScript Basics', author: 'John Doe' },
//   { title: 'Vue.js Guide', author: 'Jane Smith' },
//   { title: 'TypeScript Deep Dive', author: 'John Smith' }
// ]
```

### Mode: Intersection (AND Logic)

Match items where ALL queries match at least one field:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const articles = ref([
  { title: 'Vue 3 Composition API', tags: 'vue, composition, api' },
  { title: 'Vue 2 Options API', tags: 'vue, options' },
  { title: 'React Hooks Guide', tags: 'react, hooks, api' },
])

// Search for items containing BOTH 'vue' AND 'api'
const queries = ref(['vue', 'api'])
const { items: filtered } = useFilter(queries, articles, { mode: 'intersection' })

console.log(filtered.value)
// [
//   { title: 'Vue 3 Composition API', tags: 'vue, composition, api' },
//   { title: 'Vue 2 Options API', tags: 'vue, options' }
// ]
```

### Filtering by Specific Keys

Limit the search to specific object properties:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const employees = ref([
  { name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' },
  { name: 'Bob Smith', email: 'bob@example.com', department: 'Marketing' },
  { name: 'Charlie Johnson', email: 'charlie@example.com', department: 'Sales' },
])

// Search only in the 'name' field
const query = ref('johnson')
const { items: filtered } = useFilter(query, employees, { keys: ['name'] })

console.log(filtered.value)
// [
//   { name: 'Alice Johnson', email: 'alice@example.com', department: 'Engineering' },
//   { name: 'Charlie Johnson', email: 'charlie@example.com', department: 'Sales' }
// ]
```

### Custom Filter Function

Implement custom filtering logic for advanced use cases:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const products = ref([
  { name: 'Laptop', price: 999, inStock: true },
  { name: 'Phone', price: 599, inStock: false },
  { name: 'Tablet', price: 399, inStock: true },
])

// Custom filter: search by name and filter by price range
const priceRange = ref([300, 700])
const { items: filtered } = useFilter(priceRange, products, {
  customFilter: (query, item) => {
    if (typeof item === 'object' && item !== null) {
      const [min, max] = query as number[]
      return item.price >= min && item.price <= max && item.inStock
    }
    return false
  }
})

console.log(filtered.value)
// [{ name: 'Tablet', price: 399, inStock: true }]
```

### Empty Query Handling

When the query is empty or only whitespace, all items are returned:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

const items = ref(['apple', 'banana', 'cherry'])

const query = ref('')
const { items: filtered } = useFilter(query, items)

console.log(filtered.value)
// ['apple', 'banana', 'cherry']

query.value = '   ' // Only whitespace
console.log(filtered.value)
// ['apple', 'banana', 'cherry']
```

### Real-World Search Example

A practical example of a searchable user list:

```vue UseFilter
<script setup lang="ts">
  import { ref } from 'vue'
  import { useFilter } from '@vuetify/v0'

  interface User {
    id: number
    name: string
    email: string
    department: string
  }

  const users = ref<User[]>([
    { id: 1, name: 'Alice Johnson', email: 'alice@company.com', department: 'Engineering' },
    { id: 2, name: 'Bob Smith', email: 'bob@company.com', department: 'Marketing' },
    { id: 3, name: 'Charlie Brown', email: 'charlie@company.com', department: 'Engineering' },
    { id: 4, name: 'Diana Prince', email: 'diana@company.com', department: 'Sales' },
  ])

  const searchQuery = ref('')
  const searchFields = ref<string[]>(['name', 'email', 'department'])

  const { items: filteredUsers } = useFilter(searchQuery, users, {
    keys: searchFields.value,
    mode: 'some'
  })
</script>

<template>
  <div>
    <input
      v-model="searchQuery"
      type="text"
      placeholder="Search users..."
    />

    <div v-if="filteredUsers.length === 0">
      No users found matching "{{ searchQuery }}"
    </div>

    <ul v-else>
      <li v-for="user in filteredUsers" :key="user.id">
        <strong>{{ user.name }}</strong> - {{ user.email }} ({{ user.department }})
      </li>
    </ul>
  </div>
</template>
```

## TypeScript Usage

The composable is fully typed and supports generic type parameters:

```ts
import { ref } from 'vue'
import { useFilter } from '@vuetify/v0'

interface Product {
  id: number
  name: string
  category: string
  price: number
}

const products = ref<Product[]>([
  { id: 1, name: 'Laptop', category: 'Electronics', price: 999 },
  { id: 2, name: 'Desk', category: 'Furniture', price: 299 },
])

const query = ref('laptop')
const { items } = useFilter<Product>(query, products, {
  keys: ['name', 'category']
})

// items is typed as ComputedRef<Product[]>
console.log(items.value[0]?.name) // TypeScript knows this is a string
```

## Dependency Injection

For sharing filter configuration across component trees, use the context-based API.

### createFilter

Creates a filter context with pre-configured options:

```ts
import { createFilter } from '@vuetify/v0'

const filter = createFilter({
  mode: 'intersection',
  keys: ['name', 'email'],
})

// Use the apply method to filter arrays
const { items } = filter.apply(query, users)
```

### createFilterContext

Creates a trinity tuple for Vue's provide/inject system:

```ts
import { createFilterContext } from '@vuetify/v0'

// Create a shared filter context
export const [useSearchFilter, provideSearchFilter, searchFilter] = createFilterContext({
  namespace: 'app:search',
  mode: 'union',
  keys: ['title', 'description'],
})
```

```vue
<!-- Parent component -->
<script setup lang="ts">
  import { provideSearchFilter } from './search-filter'

  // Provide the filter context to descendants
  provideSearchFilter()
</script>
```

```vue
<!-- Child component -->
<script setup lang="ts">
  import { ref } from 'vue'
  import { useSearchFilter } from './search-filter'

  const filter = useSearchFilter()
  const query = ref('')
  const products = ref([...])

  const { items: filtered } = filter.apply(query, products)
</script>
```

### useFilterContext

Retrieves a filter context from dependency injection:

```ts
import { useFilterContext } from '@vuetify/v0'

// Get the filter context provided by an ancestor
const filter = useFilterContext('app:search')
const { items } = filter.apply(query, products)
```

## Notes

- The default filter is **case-insensitive** and uses substring matching (`.includes()`)
- Empty queries (empty string or whitespace-only) return all items unfiltered
- When using arrays of queries, individual empty values are filtered out before processing
- The `customFilter` function receives the full query parameter (single value or array) and must handle it accordingly
- Filtering is reactive: changes to the query or items array automatically update the filtered results

---

# Use Overflow
URL: https://0.vuetifyjs.com/composables/utilities/use-overflow

# useOverflow

A composable for computing how many items fit in a container based on available width, enabling responsive truncation for pagination, breadcrumbs, and similar components.

## Usage

The `useOverflow` composable provides reactive container width tracking and capacity calculation. It supports two modes: variable-width (for items with different widths like breadcrumbs) and uniform-width (for same-width items like pagination buttons).

```ts
import { useTemplateRef } from 'vue'
import { createOverflow } from '@vuetify/v0'

const containerRef = useTemplateRef('container')

// Pass container as a ref or getter for proper reactive tracking
const overflow = createOverflow({
  container: containerRef,
  gap: 8,
  reserved: 40,
})

// Check capacity
console.log(overflow.capacity.value) // Number of items that fit
console.log(overflow.isOverflowing.value) // true if items exceed container
```

## Examples

### Variable-Width Mode (Breadcrumbs)

For items with different widths, measure each item individually:

```vue UseOverflow
<script setup lang="ts">
  import { useTemplateRef } from 'vue'
  import { createOverflow } from '@vuetify/v0'

  const items = ['Home', 'Documentation', 'Components', 'Breadcrumbs']
  const containerRef = useTemplateRef('nav')

  const overflow = createOverflow({
    container: containerRef,
    gap: 8,
    reserved: 40, // Space for ellipsis
    reverse: true, // Calculate from trailing items
  })
</script>

<template>
  <nav ref="nav">
    <template v-for="(item, i) in items" :key="i">
      <span
        v-if="!overflow.isOverflowing.value || i >= items.length - overflow.capacity.value"
        :ref="el => overflow.measure(i, el)"
      >
        {{ item }}
      </span>
    </template>
    <span v-if="overflow.isOverflowing.value">...</span>
  </nav>
</template>
```

### Uniform-Width Mode (Pagination)

For items with the same width, provide `itemWidth` for efficient calculation:

```ts
import { shallowRef } from 'vue'
import { createOverflow } from '@vuetify/v0'

const containerRef = useTemplateRef('container')
const buttonWidth = shallowRef(36) // Measured from sample button

const overflow = createOverflow({
  container: containerRef,
  itemWidth: buttonWidth,
  reserved: () => buttonWidth.value * 4, // Space for nav buttons
})

// Capacity is calculated as: (availableWidth / itemWidth)
console.log(overflow.capacity.value)
```

### Measuring Items

In variable-width mode, use `measure()` to register item elements:

```ts
import { createOverflow } from '@vuetify/v0'

const overflow = createOverflow({ gap: 4 })

// Register an element at index 0
const element = document.querySelector('.item')
overflow.measure(0, element)

// Remove measurement (e.g., when element unmounts)
overflow.measure(0, undefined)

// Clear all measurements
overflow.reset()
```

### Reactive Reserved Space

Reserved space can be reactive:

```ts
import { shallowRef } from 'vue'
import { createOverflow } from '@vuetify/v0'

const navButtonCount = shallowRef(4)
const buttonWidth = 36

const overflow = createOverflow({
  itemWidth: buttonWidth,
  reserved: () => buttonWidth * navButtonCount.value,
})

// Capacity updates when navButtonCount changes
navButtonCount.value = 2
console.log(overflow.capacity.value) // More capacity available
```

### Dependency Injection

Use the context pattern for component hierarchies:

```ts
// Parent component
import { createOverflowContext } from '@vuetify/v0'

const [useOverflow, provideOverflowContext, overflow] = createOverflowContext({
  namespace: 'my-overflow',
  gap: 8,
  reserved: 100,
})

provideOverflowContext()

// Child component
import { useOverflow } from '@vuetify/v0'

const overflow = useOverflow('my-overflow')
overflow.measure(0, myElement)
```

### Reverse Mode for Trailing Items

When `reverse: true`, capacity is calculated from the end, useful for breadcrumbs:

```ts
import { createOverflow } from '@vuetify/v0'

const items = ['A', 'B', 'C', 'D', 'E'] // Variable width items
const overflow = createOverflow({
  reverse: true,
  reserved: 50, // Space for first item + ellipsis
})

// If capacity is 2, show items at indices 3 and 4 (D and E)
const startIndex = items.length - overflow.capacity.value
const visibleItems = items.slice(startIndex)
```

### Vue Component Example

```vue UseOverflow
<script setup lang="ts">
  import { ref, useTemplateRef } from 'vue'
  import { createOverflow } from '@vuetify/v0'

  const items = ref(['First', 'Second', 'Third', 'Fourth', 'Fifth'])
  const containerRef = useTemplateRef('container')

  const overflow = createOverflow({
    container: containerRef,
    gap: 8,
    reserved: 24, // Ellipsis space
  })
</script>

<template>
  <div
    ref="container"
    class="flex gap-2 overflow-hidden"
  >
    <template v-for="(item, i) in items" :key="i">
      <span
        v-if="i < overflow.capacity.value"
        :ref="el => overflow.measure(i, el)"
        class="whitespace-nowrap"
      >
        {{ item }}
      </span>
    </template>
    <span v-if="overflow.isOverflowing.value">...</span>
  </div>

  <p>
    Showing {{ Math.min(overflow.capacity.value, items.length) }} of {{ items.length }} items
  </p>
</template>
```

## Notes

- Container width is tracked via `ResizeObserver` for automatic updates
- In SSR or before measurement, `capacity` returns `Infinity` (show all items)
- Variable-width mode measures each item's `offsetWidth` plus horizontal margins
- Uniform-width mode is more efficient as it doesn't require individual measurements
- The `total` computed includes gaps between measured items
- Use `reverse: true` for breadcrumb-style components where trailing items take priority

---

# Use Pagination
URL: https://0.vuetifyjs.com/composables/utilities/use-pagination

# usePagination

A lightweight composable for managing pagination state with navigation methods and computed visible page items.

## Usage

The `usePagination` composable provides reactive pagination state management with navigation methods and automatic computation of visible page items with ellipsis support.

```ts
import { ref } from 'vue'
import { createPagination } from '@vuetify/v0'

const pagination = createPagination({
  size: 200, // Total items
  itemsPerPage: 10,
  visible: 5,
})

console.log(pagination.pages) // 20 (200 items / 10 per page)
console.log(pagination.items.value)
// [
//   { type: 'page', value: 1 },
//   { type: 'page', value: 2 },
//   { type: 'page', value: 3 },
//   { type: 'ellipsis', value: '…' },
//   { type: 'page', value: 20 }
// ]
```

## Examples

### Basic Navigation

```ts
import { createPagination } from '@vuetify/v0'

const pagination = createPagination({
  size: 100,
  itemsPerPage: 10,
})

console.log(pagination.page.value) // 1
console.log(pagination.pages) // 10

pagination.next()
console.log(pagination.page.value) // 2

pagination.select(5)
console.log(pagination.page.value) // 5

pagination.last()
console.log(pagination.page.value) // 10
```

### v-model Support

Pass a ref to sync the page value:

```ts
import { shallowRef } from 'vue'
import { createPagination } from '@vuetify/v0'

const page = shallowRef(1)
const pagination = createPagination({
  page,
  size: 100,
})

// Changes to either sync automatically
pagination.next()
console.log(page.value) // 2

page.value = 5
console.log(pagination.page.value) // 5
```

### Computing Page Range

Use `pageStart` and `pageStop` to slice your data:

```ts
import { computed, ref } from 'vue'
import { createPagination } from '@vuetify/v0'

const allItems = ref([...Array(100).keys()].map(i => ({ id: i + 1 })))
const pagination = createPagination({
  size: () => allItems.value.length,
  itemsPerPage: 10,
})

const visibleItems = computed(() =>
  allItems.value.slice(pagination.pageStart.value, pagination.pageStop.value)
)

// Page 1: items 0-9 (ids 1-10)
console.log(visibleItems.value.length) // 10
console.log(visibleItems.value[0].id) // 1

pagination.next()
// Page 2: items 10-19 (ids 11-20)
console.log(visibleItems.value[0].id) // 11
```

### Rendering Page Items

The `items` computed provides an array suitable for rendering:

```ts
import { createPagination } from '@vuetify/v0'

const pagination = createPagination({
  size: 200,
  visible: 7,
  page: 10,
})

console.log(pagination.items.value)
// [
//   { type: 'page', value: 1 },
//   { type: 'ellipsis', value: '…' },
//   { type: 'page', value: 9 },
//   { type: 'page', value: 10 },
//   { type: 'page', value: 11 },
//   { type: 'ellipsis', value: '…' },
//   { type: 'page', value: 20 }
// ]
```

### Reactive Size

Size can be reactive for dynamic data:

```ts
import { ref } from 'vue'
import { createPagination } from '@vuetify/v0'

const totalItems = ref(100)
const pagination = createPagination({
  size: () => totalItems.value,
  itemsPerPage: 10,
})

console.log(pagination.pages) // 10

totalItems.value = 50
console.log(pagination.pages) // 5
```

### Reactive Items Per Page

```ts
import { shallowRef } from 'vue'
import { createPagination } from '@vuetify/v0'

const itemsPerPage = shallowRef(10)
const pagination = createPagination({
  size: 100,
  itemsPerPage,
})

console.log(pagination.pages) // 10

itemsPerPage.value = 25
console.log(pagination.pages) // 4
```

### Custom Ellipsis

```ts
import { createPagination } from '@vuetify/v0'

const pagination = createPagination({
  size: 200,
  visible: 5,
  ellipsis: '...',
})

const ellipsis = pagination.items.value.find(item => item.type === 'ellipsis')
console.log(ellipsis?.value) // '...'
```

### Dependency Injection

Use the context pattern for component hierarchies:

```ts
// Parent component
import { createPaginationContext } from '@vuetify/v0'

const [usePagination, providePaginationContext] = createPaginationContext({
  namespace: 'my-pagination',
  size: 200,
})

providePaginationContext()

// Child component
import { usePagination } from '@vuetify/v0'

const pagination = usePagination('my-pagination')
pagination.next()
```

### Vue Component Example

```vue UsePagination
<script setup lang="ts">
  import { computed, ref } from 'vue'
  import { createPagination } from '@vuetify/v0'

  interface Item {
    id: number
    name: string
  }

  const allItems = ref<Item[]>([
    { id: 1, name: 'Item 1' },
    { id: 2, name: 'Item 2' },
    // ... more items
  ])

  const pagination = createPagination({
    size: () => allItems.value.length,
    itemsPerPage: 10,
    visible: 5,
  })

  const displayedItems = computed(() =>
    allItems.value.slice(pagination.pageStart.value, pagination.pageStop.value)
  )
</script>

<template>
  <ul>
    <li v-for="item in displayedItems" :key="item.id">
      {{ item.name }}
    </li>
  </ul>

  <nav class="flex gap-2">
    <button :disabled="pagination.isFirst.value" @click="pagination.prev()">
      Previous
    </button>

    <template v-for="(item, index) in pagination.items.value" :key="index">
      <span v-if="item.type === 'ellipsis'">{{ item.value }}</span>
      <button
        v-else
        :class="{ active: pagination.page.value === item.value }"
        @click="pagination.select(item.value as number)"
      >
        {{ item.value }}
      </button>
    </template>

    <button :disabled="pagination.isLast.value" @click="pagination.next()">
      Next
    </button>
  </nav>
</template>
```

## Notes

- Page numbers are **1-indexed** (first page is 1, not 0)
- `pageStart` and `pageStop` are **0-indexed** for array slicing
- `pageStop` is clamped to `size` on the last page (won't exceed total items)
- The `items` array maintains a consistent length equal to `visible` when there are enough pages
- Ellipsis is only shown when there are more pages than can be displayed
- Navigation methods (`next`, `prev`, `select`) automatically clamp to valid page range

---

# Use Virtual
URL: https://0.vuetifyjs.com/composables/utilities/use-virtual

<script setup>
import VirtualListExample from '@/examples/composables/use-virtual/basic.vue'
import VirtualListExampleRaw from '@/examples/composables/use-virtual/basic.vue?raw'
</script>

# useVirtual

Virtual scrolling composable for efficiently rendering large lists by only rendering visible items.

## Overview

The `useVirtual` composable enables high-performance rendering of large datasets (thousands or millions of items) by only rendering the items currently visible in the viewport plus a small overscan buffer. This dramatically reduces DOM nodes and improves performance.

## Usage

## Architecture

The rendering pipeline transforms scroll events into visible item ranges:

```mermaid
flowchart LR
  subgraph Inputs
    A[scroll event]
    B[viewport height]
    C[item height]
  end

  subgraph Calculate
    D[visible range]
    E[overscan buffer]
    F[offset position]
  end

  subgraph Output
    G[sliced items]
    H[transform style]
  end

  A --> D
  B --> D
  C --> D
  D --> E
  E --> F
  F --> G
  F --> H
```

## Template Structure

The virtual list requires a specific template structure:

```vue UseVirtual
<template>
  <div
    ref="element"
    class="h-[600px] overflow-y-auto"
    @scroll="scroll"
  >
    <!-- Top padding for items before visible range -->
    <div :style="{ height: `${offset}px` }" />

    <!-- Rendered items (only visible ones) -->
    <div
      v-for="item in items"
      :key="item.index"
      class="h-[80px]"
    >
      {{ item.raw }}
    </div>

    <!-- Bottom padding for items after visible range -->
    <div :style="{ height: `${size}px` }" />
  </div>
</template>
```

## Usage Patterns

### Fixed Heights

Most performant option. Specify a fixed `itemHeight`:

```vue UseVirtual
<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { useVirtual } from '@vuetify/v0'

  const items = shallowRef(Array.from({ length: 10000 }, (_, i) => ({
    id: i,
    name: `Item ${i + 1}`,
  })))

  const { element, items: virtualItems, offset, size, scroll } =
    useVirtual(items, {
      itemHeight: 80,
      overscan: 5
    })
</script>

<template>
  <div
    ref="element"
    class="h-[600px] overflow-y-auto"
    @scroll="scroll"
  >
    <div :style="{ height: `${offset}px` }" />

    <div
      v-for="item in virtualItems"
      :key="item.index"
      class="h-[80px] px-4 flex items-center border-b"
    >
      <span class="text-gray-400 mr-4">#{{ item.index + 1 }}</span>
      <span class="font-medium">{{ item.raw.name }}</span>
    </div>

    <div :style="{ height: `${size}px` }" />
  </div>
</template>
```

### Dynamic Heights

For variable item heights, use `itemHeight: null` and measure each item:

```vue UseVirtual
<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { useVirtual, useResizeObserver } from '@vuetify/v0'

  const items = shallowRef(Array.from({ length: 1000 }, (_, i) => ({
    id: i,
    text: i % 3 === 0 ? 'Short' : 'A longer message that wraps...'
  })))

  const { element, items: virtualItems, offset, size, scroll, resize } =
    useVirtual(items, { itemHeight: null })

  function setupItemResize(el: Element | undefined, index: number) {
    if (!el) return
    const { stop } = useResizeObserver(
      shallowRef(el),
      entries => {
        const entry = entries[0]
        if (entry) {
          resize(index, entry.contentRect.height)
        }
      },
      { immediate: true }
    )
    return stop
  }
</script>

<template>
  <div
    ref="element"
    class="h-[600px] overflow-y-auto"
    @scroll="scroll"
  >
    <div :style="{ height: `${offset}px` }" />

    <div
      v-for="item in virtualItems"
      :key="item.index"
      :ref="el => setupItemResize(el as Element, item.index)"
      class="p-4 border-b"
    >
      {{ item.raw.text }}
    </div>

    <div :style="{ height: `${size}px` }" />
  </div>
</template>
```

### Reverse Direction (Chat Apps)

Perfect for chat applications where new messages appear at the bottom:

```vue UseVirtual
<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { useVirtual } from '@vuetify/v0'

  const messages = shallowRef([...])

  const { element, items: virtualItems, offset, size, scroll } =
    useVirtual(messages, {
      itemHeight: 80,
      direction: 'reverse', // Scroll anchored to bottom
    })
</script>
```

**Behavior:**
- Automatically scrolls to bottom on mount
- New items added maintain scroll position
- Ideal for message lists and activity feeds

### Scroll Anchoring

Maintain scroll position when prepending items (e.g., loading older messages):

```vue UseVirtual
<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { useVirtual } from '@vuetify/v0'

  const messages = shallowRef([...])

  const { element, items: virtualItems, offset, size, scroll } =
    useVirtual(messages, {
      itemHeight: 80,
      anchor: 'start', // Maintain position relative to first visible item
      anchorSmooth: true, // Smooth transition
    })

  async function loadOlder() {
    const olderMessages = await fetchOlderMessages()
    messages.value = [...olderMessages, ...messages.value]
    // Scroll position maintained automatically!
  }
</script>
```

### Infinite Scroll

Load more data when scrolling near edges:

```vue UseVirtual
<script setup lang="ts">
  import { shallowRef } from 'vue'
  import { useVirtual } from '@vuetify/v0'

  const items = shallowRef([...])

  const { element, items: virtualItems, offset, size, scroll, state, reset } =
    useVirtual(items, {
      itemHeight: 50,

      onStartReached: async (distance) => {
        if (state.value === 'loading') return

        state.value = 'loading'
        const olderItems = await loadOlderItems()

        if (olderItems.length === 0) {
          state.value = 'empty'
        } else {
          items.value = [...olderItems, ...items.value]
          state.value = 'ok'
        }
      },
      startThreshold: 200, // Trigger when within 200px of top

      onEndReached: async (distance) => {
        if (state.value === 'loading') return

        state.value = 'loading'
        const newerItems = await loadNewerItems()

        if (newerItems.length === 0) {
          state.value = 'empty'
        } else {
          items.value = [...items.value, ...newerItems]
          state.value = 'ok'
        }
      },
      endThreshold: 200, // Trigger when within 200px of bottom
    })
</script>
```

### Enhanced Scroll To

Scroll to specific items with fine-grained control:

```ts
// Basic scroll
scrollTo(100) // Scroll to item 100 (top of viewport)

// Smooth scroll
scrollTo(100, { behavior: 'smooth' })

// Center item in viewport
scrollTo(100, { block: 'center' })

// Align to bottom of viewport
scrollTo(100, { block: 'end' })

// Only scroll if not visible
scrollTo(100, { block: 'nearest' })

// Add custom offset
scrollTo(100, { offset: 50, behavior: 'smooth' })
```

## Performance Tips

1. **Use fixed heights when possible** - Much faster than dynamic measurement
2. **Use `item.index` as key** - More stable than `item.id` for virtual lists
3. **Keep item templates simple** - Minimize DOM complexity per item
4. **Avoid deep reactivity** - Use `shallowRef` for large item arrays
5. **Debounce expensive operations** - Like search/filter on large datasets
6. **Tune overscan for your use case**:
   - **Lower overscan (1-3)** - Better memory usage, may see blank items during fast scrolling
   - **Default overscan (5)** - Balanced for most use cases
   - **Higher overscan (10+)** - Smoother scrolling, uses more memory

## Overscan Configuration

The `overscan` option controls how many extra items are rendered before and after the visible viewport:

```ts
// Low overscan - minimal memory, may see flicker on fast scroll
useVirtual(items, { itemHeight: 50, overscan: 2 })

// Default overscan - balanced (default: 5)
useVirtual(items, { itemHeight: 50 }) // same as overscan: 5

// High overscan - smoothest scrolling, more memory
useVirtual(items, { itemHeight: 50, overscan: 15 })
```

**When to adjust:**
- **Mobile devices**: Lower overscan (2-3) to reduce memory pressure
- **Fast scroll animations**: Higher overscan (10-15) for buttery smooth scrolling
- **Large complex items**: Lower overscan (1-2) if items are heavy to render
- **Simple text rows**: Higher overscan (8-10) since they're cheap to render

## Common Patterns

### Adding Items Dynamically

```ts
const items = shallowRef([...])

// Add more items
items.value = [...items.value, ...newItems]
// Virtual list automatically updates!
```

### Filtering Items

```ts
const items = shallowRef([...])

// Filter items
items.value = items.value.filter(item => item.active)
// Offsets and padding recalculate automatically!
```

## Accessibility

The virtual list itself is headless and provides no ARIA attributes. You should add appropriate ARIA roles based on your use case:

```vue UseVirtual
<div
  ref="element"
  role="list"
  aria-label="Products"
  class="h-[600px] overflow-y-auto"
  @scroll="scroll"
>
  <div :style="{ height: `${offset}px` }" aria-hidden="true" />

  <div
    v-for="item in items"
    :key="item.index"
    role="listitem"
    class="h-[80px]"
  >
    {{ item.raw }}
  </div>

  <div :style="{ height: `${size}px` }" aria-hidden="true" />
</div>
```

## TypeScript

The composable is fully typed:

```ts
import { shallowRef } from 'vue'
import { useVirtual } from '@vuetify/v0'
import type { VirtualOptions, VirtualContext } from '@vuetify/v0'

interface Product {
  id: number
  name: string
  price: number
}

const products = shallowRef<Product[]>([...])

const options: VirtualOptions = {
  itemHeight: 80,
  overscan: 5,
}

const virtual: VirtualContext<Product> = useVirtual(products, options)

// Items are typed as VirtualItem<Product>
virtual.items.value.forEach(item => {
  console.log(item.raw.name) // TypeScript knows about Product properties
})
```

---

# To Reactive
URL: https://0.vuetifyjs.com/utilities/to-reactive

# toReactive

A utility that converts a `ref` of an object, `Map`, or `Set` into a reactive object, maintaining reactivity for complex objects.



---

# api
URL: https://0.vuetifyjs.com/api

# API Reference

Complete API documentation for all @vuetify/v0 components and composables.

## Components

Detailed API reference for each component including props, events, and slots.

| Component | Description |
| - | - |
| [Atom](/api/atom) | Polymorphic element base component |
| [Avatar](/api/avatar) | Image with fallback support |
| [ExpansionPanel](/api/expansion-panel) | Collapsible accordion panels |
| [Group](/api/group) | Multi-selection with tri-state |
| [Pagination](/api/pagination) | Page navigation component |
| [Popover](/api/popover) | Anchor-positioned popups |
| [Selection](/api/selection) | Multi-selection state provider |
| [Single](/api/single) | Single-selection provider |
| [Step](/api/step) | Sequential navigation provider |

## Composables

Detailed API reference for each composable including options, properties, and methods.

| Composable | Description |
| - | - |
| [useRegistry](/api/use-registry) | Item registration and tracking |
| [useSelection](/api/use-selection) | Selection state management |
| [useTheme](/api/use-theme) | Theme management and toggling |
| [useStorage](/api/use-storage) | Persistent storage abstraction |
| [useLogger](/api/use-logger) | Development logging utilities |

---

# Releases
URL: https://0.vuetifyjs.com/releases

<script setup>
  import DocsReleases from '@/components/docs/DocsReleases.vue'
</script>

# Release Notes

Stay up to date with the latest releases and changes in Vuetify v0. Select a version below to view its release notes.



---

# Roadmap
URL: https://0.vuetifyjs.com/roadmap

# Roadmap

Track the development of @vuetify/v0. Milestones are organized by time horizon:

- **Now** — Actively in development, due within 30 days
- **Next** — Planned for the near future, due within 90 days
- **Later** — On the radar, no immediate timeline
- **Completed** — Released milestones



---

# storybook
URL: https://0.vuetifyjs.com/storybook

# Storybook

Storybook provides an interactive environment for exploring Vuetify0 components in isolation. Browse through component variations, test different states, and see live examples of each component.

## Features

- **Interactive Examples** — Explore each component with working demos
- **Multiple Variants** — See different configurations and use cases
- **Live Controls** — Adjust props and see changes in real-time
- **Accessibility** — Verify ARIA attributes and keyboard navigation

## Components Covered

All Vuetify0 headless components have dedicated stories:

- **Atom** — Polymorphic rendering, renderless mode
- **Avatar** — Image loading with fallbacks
- **ExpansionPanel** — Accordion and multi-expand modes
- **Group** — Multi-selection with tri-state
- **Pagination** — Page navigation controls
- **Popover** — Dropdown menus and tooltips
- **Selection** — Single and multiple selection
- **Single** — Tabs, segmented controls
- **Step** — Wizard and stepper patterns

<div class="mt-8">
  <router-link
    class="inline-flex items-center gap-2 px-6 py-3 bg-primary text-on-primary rounded-lg font-semibold hover:opacity-90 transition-opacity"
    to="/storybook/view"
  >
    Launch Storybook
    <svg class="size-5" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24">
      <path d="M13 7l5 5m0 0l-5 5m5-5H6" stroke-linecap="round" stroke-linejoin="round" />
    </svg>
  </router-link>
</div>

---