shadcn-vue-inertia — Claude Code skill: what it does, how to install
shadcn-vue-inertia adapts shadcn-vue UI components for Inertia.js Rails and Vue 3 instead of Nuxt. Guides form binding, table sorting, dialogs, and dark mode setup.
MIT 122 installs ★ 72 updated 2026-09-01
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a claude-codeWhat shadcn-vue-inertia does
Standard shadcn-vue blueprints depend heavily on Nuxt utilities and vee-validate form wrappers. This skill guides the agent to replace those patterns with native Inertia.js tooling. It swaps Nuxt routing and fetch hooks for Inertia props and router calls, keeping the front end tightly integrated with Rails controllers.
Form architecture changes fundamentally. The components FormField, FormItem, and FormMessage crash without vee-validate runtime context. The skill enforces plain shadcn inputs with explicit name attributes inside the Inertia <Form> component, pulling errors directly from scoped slots. Using v-model with <Form> is blocked because the component submits native input values instead.
Because vite-plugin-ruby handles path resolution, adding @/ aliases directly to vite.config.ts causes conflicts; configure them only inside tsconfig.json. The skill also provides a head script snippet to prevent theme flashing on reload.
What it helps with
- adapt vee-validate shadcn forms to Inertia Form inputs
- configure dark mode without Nuxt color-mode to stop FOUC
- implement server-driven sorting for data tables via Inertia router
- wire Sonner toast alerts to Rails flash messages
Example prompts for the agent
- Build a user profile form using shadcn-vue inputs inside Inertia Form
- Create a shadcn modal that syncs visibility with router.replaceProp
- Set up theme toggling using the dark HTML class without Nuxt packages
How to install shadcn-vue-inertia
1Skills CLI (Vercel)
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a claude-code2Manually: put the files in place
~/.claude/skills/shadcn-vue-inertia/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/shadcn-vue-inertia/
1Skills CLI (Vercel)
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a codex2Manually: put the files in place
.agents/skills/shadcn-vue-inertia/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a cursor2Manually: put the files in place
.cursor/skills/shadcn-vue-inertia/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install inertia-rails/skills skills/shadcn-vue-inertia2Manually: put the files in place
.github/skills/shadcn-vue-inertia/SKILL.md1Skills CLI (Vercel)
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a gemini-cli2Platform CLI
gemini skills install https://github.com/inertia-rails/skills --path skills/shadcn-vue-inertiaManually: put the files in place
.devin/skills/shadcn-vue-inertia/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about shadcn-vue-inertia
How to install shadcn-vue-inertia in Claude Code?
Run npx skills add inertia-rails/skills --skill shadcn-vue-inertia -a claude-code.
What does shadcn-vue-inertia do?
It gives coding agents blueprints to run shadcn-vue inside Vue 3 Inertia Rails apps without Nuxt conventions.
Why avoid shadcn FormField components in Inertia?
They rely internally on vee-validate context and crash without it. Inertia forms require native name attributes on base inputs instead.
Source text
SKILL.md · MIT
---
name: shadcn-vue-inertia
description: >-
shadcn-vue component integration for Inertia Rails Vue 3 (NOT Nuxt): forms, dialogs, tables, toasts, dark mode,
and more. Use when building UI with shadcn-vue components in an Inertia + Vue app or adapting shadcn-vue
examples from Nuxt. Wire shadcn-vue inputs to Inertia Form via name attribute and #default scoped slot.
Flash toasts require Rails flash_keys initializer config.
---
# shadcn-vue for Inertia Rails
shadcn-vue patterns adapted for Inertia.js + Rails + Vue 3. NOT Nuxt.
**Before using a shadcn-vue example, ask:**
- **Does it use Nuxt-specific APIs?** (`useRouter`, `useFetch`, `<NuxtLink>`) → Replace with Inertia `router`, server props, `<Link>`
- **Does it use `vee-validate` + `zod`?** → Replace with Inertia `<Form>` + `name` attributes. Inertia handles CSRF, errors, redirects, processing state.
## Key Differences from Nuxt Defaults
| shadcn-vue default (Nuxt) | Inertia equivalent |
|---|---|
| `useFetch` / `useAsyncData` | Server-rendered props via controller |
| `useRouter()` (Nuxt) | `router` from `@inertiajs/vue3` |
| `<NuxtLink>` | `<Link>` from `@inertiajs/vue3` |
| `vee-validate` + `zod` | Inertia `<Form>` component |
| `FormField`, `FormItem`, `FormMessage` | Plain `<Input name="...">` + `errors.field` |
| `useHead()` (Nuxt) | `<Head>` from `@inertiajs/vue3` |
**NEVER use shadcn-vue's `FormField`, `FormItem`, `FormLabel`, `FormMessage` components** —
they depend on vee-validate's form context internally and will crash without it.
Use plain shadcn-vue `Input`/`Label`/`Select` with `name` attributes inside Inertia `<Form>`,
and render errors from the scoped slot's `errors` object.
## Setup
`npx shadcn-vue@latest init`. Add `@/` resolve aliases to `tsconfig.json` if not present.
**Do NOT add `@/` resolve aliases to `vite.config.ts`** — `vite-plugin-ruby` already provides them.
## shadcn-vue Inputs in Inertia `<Form>`
Use plain shadcn-vue `Input`/`Label`/`Button` with `name` attributes inside Inertia `<Form>`.
See `inertia-rails-forms` skill (+ `references/vue.md`) for full `<Form>` API.
**The key pattern:** Replace shadcn-vue's `FormField`/`FormItem`/`FormMessage` with plain
components + manual error display:
```vue
<script setup lang="ts">
import { Form } from '@inertiajs/vue3'
import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
import { Button } from '@/components/ui/button'
</script>
<template>
<Form method="post" action="/users">
<template #default="{ errors, processing }">
<div class="space-y-4">
<div>
<Label for="name">Name</Label>
<Input id="name" name="name" />
<p v-if="errors.name" class="text-sm text-destructive">{{ errors.name }}</p>
</div>
<div>
<Label for="email">Email</Label>
<Input id="email" name="email" type="email" />
<p v-if="errors.email" class="text-sm text-destructive">{{ errors.email }}</p>
</div>
<Button type="submit" :disabled="processing">
{{ processing ? 'Creating...' : 'Create User' }}
</Button>
</div>
</template>
</Form>
</template>
```
**`<Select>` requires `name` prop** for Inertia `<Form>` integration:
```vue
<template>
<Select name="role" default-value="member">
<SelectTrigger><SelectValue placeholder="Select role" /></SelectTrigger>
<SelectContent>
<SelectItem value="admin">Admin</SelectItem>
<SelectItem value="member">Member</SelectItem>
</SelectContent>
</Select>
</template>
```
## Dialog with Inertia Navigation
```vue
<script setup lang="ts">
import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog'
import { router } from '@inertiajs/vue3'
defineProps<{ open: boolean; user: User }>()
</script>
<template>
<Dialog
:open="open"
@update:open="(isOpen) => { if (!isOpen) router.replaceProp('show_dialog', false) }"
>
<DialogContent>
<DialogHeader>
<DialogTitle>{{ user.name }}</DialogTitle>
</DialogHeader>
<!-- content -->
</DialogContent>
</Dialog>
</template>
```
## Table with Server-Side Sorting
```vue
<script setup lang="ts">
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
import { router } from '@inertiajs/vue3'
defineProps<{ users: User[]; sort: string }>()
const handleSort = (column: string) => {
router.get('/users', { sort: column }, { preserveState: true })
}
</script>
<template>
<Table>
<TableHeader>
<TableRow>
<TableHead class="cursor-pointer" @click="handleSort('name')">
Name {{ sort === 'name' ? '↑' : '' }}
</TableHead>
<TableHead>Email</TableHead>
</TableRow>
</TableHeader>
<TableBody>
<TableRow v-for="user in users" :key="user.id">
<TableCell>{{ user.name }}</TableCell>
<TableCell>{{ user.email }}</TableCell>
</TableRow>
</TableBody>
</Table>
</template>
```
Use `<Link>` (not `<a>`) for row links to preserve SPA navigation.
## Toast with Flash Messages
Flash config (`flash_keys`) is in `inertia-rails-controllers`. Flash access
(`usePage().flash`) is in `inertia-rails-pages`. This section covers **toast UI wiring only**.
**MANDATORY — READ ENTIRE FILE** when implementing flash-based toasts with Sonner:
[`references/flash-toast.md`](references/flash-toast.md) (~80 lines) — full `useFlash`
composable and Sonner toast provider. **Do NOT load** if only reading flash values without toast UI.
## Dark Mode (No Nuxt color-mode)
`npx shadcn-vue@latest init` generates CSS variables for light/dark and
`@custom-variant dark (&:is(.dark *));` in your CSS (Tailwind v4). No extra
setup needed for the variables themselves.
**CRITICAL — prevent flash of wrong theme (FOUC):** Add an inline script in
`<head>` (before Vue hydrates):
```erb
<%# app/views/layouts/application.html.erb — in <head>, before any stylesheets %>
<script>
document.documentElement.classList.toggle(
"dark",
localStorage.appearance === "dark" ||
(!("appearance" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches),
);
</script>
```
Use a `useAppearance` composable (light/dark/system modes, localStorage persistence,
`matchMedia` listener) instead of Nuxt color-mode. Toggle via `.dark` class on
`<html>` — no provider needed.
## Vue-Specific Gotchas
**`v-model` does NOT work with Inertia `<Form>`** — `<Form>` reads values from
input `name` attributes on submit, not from Vue's reactivity system. Using
`v-model` creates a second source of truth that `<Form>` ignores:
```vue
<!-- BAD — v-model value is ignored by <Form> on submit -->
<Form method="post" action="/users">
<Input v-model="name" />
</Form>
<!-- GOOD — name attribute is what <Form> reads -->
<Form method="post" action="/users">
<Input name="name" />
</Form>
```
Use `v-model` only with `useForm` (where you explicitly manage `form.name`).
**`usePage()` returns a reactive object — use `computed()` for derived values:**
```vue
<script setup lang="ts">
import { usePage } from '@inertiajs/vue3'
import { computed } from 'vue'
const page = usePage()
// BAD — not reactive, won't update when page changes:
// const user = page.props.auth.user
// GOOD — reactive, updates on navigation:
const user = computed(() => page.props.auth.user)
</script>
```
Without `computed()`, destructured values freeze at their initial state and
won't update after Inertia navigation.
**`@update:open` vs `@close` for Dialog** — shadcn-vue Dialog emits
`update:open`, not `close`. Using `@close` silently does nothing:
```vue
<!-- BAD — @close is not emitted by shadcn-vue Dialog -->
<Dialog @close="handleClose">
<!-- GOOD — @update:open fires on open AND close -->
<Dialog :open="open" @update:open="(isOpen) => { if (!isOpen) handleClose() }">
```
## Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| `FormField`/`FormMessage` crash | Using shadcn-vue form components that depend on vee-validate | Replace with plain `Input`/`Label` + `errors.field` display |
| `Select` value not submitted | Missing `name` prop | Add `name="field"` to `<Select>` |
| Dialog closes unexpectedly | Missing or wrong `@update:open` handler | Use `@update:open="(open) => { if (!open) closeHandler() }"` |
| Flash of wrong theme (FOUC) | Missing inline `<script>` in `<head>` | Add dark mode script before stylesheets |
| `v-model` value not submitted | `<Form>` reads `name` attrs, not Vue reactive state | Use `name` attribute; reserve `v-model` for `useForm` only |
| Shared props stale after navigation | Destructured `usePage()` without `computed()` | Wrap derived values in `computed(() => ...)` |
## Related Skills
- **Form component** → `inertia-rails-forms` + `references/vue.md` (`<Form>` scoped slot, useForm)
- **Flash config** → `inertia-rails-controllers` (flash_keys initializer)
- **Flash access** → `inertia-rails-pages` + `references/vue.md` (usePage().flash)
- **URL-driven dialogs** → `inertia-rails-pages` + `references/vue.md` (router.get pattern)
## References
Load [`references/components.md`](references/components.md) (~200 lines) when building
shadcn-vue components beyond those shown above (Accordion, Sheet, Tabs, DropdownMenu,
AlertDialog with Inertia patterns).
**Do NOT load** `components.md` for basic Form, Select, Dialog, or Table usage —
the examples above are sufficient.
© inertia-rails · MIT · inertia-rails/skills