shadcn-svelte for Inertia Rails

shadcn-svelte (bits-ui) patterns adapted for Inertia.js + Rails + Svelte. NOT SvelteKit.

Before using a shadcn-svelte example, ask:

Does it use SvelteKit-specific APIs? (goto, $app/navigation, load functions, +page.svelte) → Replace with Inertia router, server props, page components
Does it use sveltekit-superforms + zod? → Replace with Inertia <Form> + name attributes. Inertia handles CSRF, errors, redirects, processing state.

Key Differences from SvelteKit Defaults

shadcn-svelte default (SvelteKit)	Inertia equivalent
`goto()` from `$app/navigation`	`router` from `@inertiajs/svelte`
`load` functions	Server-rendered props via Rails controller
`+page.svelte` / `+layout.svelte`	Default exports with module script layout
`sveltekit-superforms` + `zod`	Inertia `<Form>` component
`<svelte:head>` (SvelteKit auto-manages)	`<svelte:head>` (same — no Inertia `<Head>` in Svelte)

Setup

npx shadcn-svelte@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-svelte Inputs in Inertia `<Form>`

Use plain shadcn-svelte Input/Label/Button with name attributes inside Inertia <Form>. See inertia-rails-forms skill (+ references/svelte.md) for full <Form> API.

The key pattern: Use {#snippet} to access form state:

<script lang="ts">
  import { Form } from '@inertiajs/svelte'
  import { Input } from '$lib/components/ui/input'
  import { Label } from '$lib/components/ui/label'
  import { Button } from '$lib/components/ui/button'
</script>

<Form method="post" action="/users">
  {#snippet children({ errors, processing })}
    <div class="space-y-4">
      <div>
        <Label for="name">Name</Label>
        <Input id="name" name="name" />
        {#if errors.name}<p class="text-sm text-destructive">{errors.name}</p>{/if}
      </div>

      <div>
        <Label for="email">Email</Label>
        <Input id="email" name="email" type="email" />
        {#if errors.email}<p class="text-sm text-destructive">{errors.email}</p>{/if}
      </div>

      <Button type="submit" disabled={processing}>
        {processing ? 'Creating...' : 'Create User'}
      </Button>
    </div>
  {/snippet}
</Form>

Svelte 4: <Form let:errors let:processing> instead of {#snippet}.

<Select> requires name prop for Inertia <Form> integration:

<Select name="role" value="member">
  <SelectTrigger><SelectValue placeholder="Select role" /></SelectTrigger>
  <SelectContent>
    <SelectItem value="admin">Admin</SelectItem>
    <SelectItem value="member">Member</SelectItem>
  </SelectContent>
</Select>

Dialog with Inertia Navigation

<script lang="ts">
  import { Dialog, DialogContent, DialogHeader, DialogTitle } from '$lib/components/ui/dialog'
  import { router } from '@inertiajs/svelte'

  let { open, user }: { open: boolean; user: User } = $props()
</script>

<Dialog
  {open}
  onOpenChange={(isOpen) => { if (!isOpen) router.replaceProp('show_dialog', false) }}
>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>{user.name}</DialogTitle>
    </DialogHeader>
    <!-- content -->
  </DialogContent>
</Dialog>

Svelte 4: on:openChange instead of onOpenChange.

Table with Server-Side Sorting

<script lang="ts">
  import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '$lib/components/ui/table'
  import { router } from '@inertiajs/svelte'

  let { users, sort }: { users: User[]; sort: string } = $props()

  const handleSort = (column: string) => {
    router.get('/users', { sort: column }, { preserveState: true })
  }
</script>

<Table>
  <TableHeader>
    <TableRow>
      <TableHead class="cursor-pointer" onclick={() => handleSort('name')}>
        Name {sort === 'name' ? '↑' : ''}
      </TableHead>
      <TableHead>Email</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {#each users as user (user.id)}
      <TableRow>
        <TableCell>{user.name}</TableCell>
        <TableCell>{user.email}</TableCell>
      </TableRow>
    {/each}
  </TableBody>
</Table>

Use <Link> or use:inertia (not <a>) for row links to preserve SPA navigation.

Toast with Flash Messages

Flash config (flash_keys) is in inertia-rails-controllers. Flash access ($page.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 (~80 lines) — full flash watcher and svelte-sonner integration. Do NOT load if only reading flash values without toast UI.

Dark Mode

npx shadcn-svelte@latest init generates CSS variables for light/dark and @custom-variant dark (&:is(.dark *)); in your CSS (Tailwind v4).

CRITICAL — prevent flash of wrong theme (FOUC): Add an inline script in <head> (before Svelte hydrates):

<%# 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 pattern (light/dark/system modes, localStorage persistence, matchMedia listener). Toggle via .dark class on <html>.

`<svelte:head>` Instead of `<Head>`

Svelte uses native <svelte:head> — there is no Inertia <Head> component for Svelte. This applies in shadcn patterns too (e.g., setting page title in dialog views):

<svelte:head>
  <title>{user.name} - Profile</title>
</svelte:head>

Svelte-Specific Gotchas

bind:value does NOT work with Inertia <Form> — <Form> reads values from input name attributes on submit, not from Svelte's reactive bindings. Using bind:value creates a second source of truth that <Form> ignores:

<!-- BAD — bind:value is ignored by <Form> on submit -->
<Form method="post" action="/users">
  <Input bind:value={name} />
</Form>

<!-- GOOD — name attribute is what <Form> reads -->
<Form method="post" action="/users">
  <Input name="name" />
</Form>

Use bind:value only with useForm (where you explicitly manage $form.name).

$page store updates are reactive, but destructured values are not:

<script lang="ts">
  import { page } from '@inertiajs/svelte'

  // BAD — snapshot, won't update after navigation:
  // let user = $page.props.auth.user

  // GOOD — use $derived for reactive access:
  let user = $derived($page.props.auth.user)
</script>

Svelte 4: use $: user = $page.props.auth.user (reactive statement).

use:inertia directive as alternative to <Link> — for elements that can't be <Link> (e.g., table rows, custom components), use the action:

<script lang="ts">
  import { inertia } from '@inertiajs/svelte'
</script>

<tr use:inertia={{ href: `/users/${user.id}` }} class="cursor-pointer">
  <td>{user.name}</td>
</tr>

bits-ui transition props and Inertia navigation — bits-ui components with transition* props may show stale content during Inertia page transitions if the exit animation outlasts the navigation. Set short durations or use forceMount on content that depends on page props.

Troubleshooting

Symptom	Cause	Fix
Form components crash	Using shadcn-svelte form components that depend on superforms	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 `onOpenChange` handler	Use `onOpenChange={(open) => { if (!open) closeHandler() }}`
Flash of wrong theme (FOUC)	Missing inline `<script>` in `<head>`	Add dark mode script before stylesheets
`bind:value` not submitted	`<Form>` reads `name` attrs, not Svelte bindings	Use `name` attribute; reserve `bind:value` for `useForm` only
Shared props stale after navigation	Destructured `$page` without `$derived`	Use `$derived($page.props.auth.user)` for reactive access

Related Skills

Form component → inertia-rails-forms + references/svelte.md (<Form> snippet, useForm)
Flash config → inertia-rails-controllers (flash_keys initializer)
Flash access → inertia-rails-pages + references/svelte.md ($page.flash)
URL-driven dialogs → inertia-rails-pages + references/svelte.md (router.get pattern)
use:inertia directive → inertia-rails-pages + references/svelte.md

References

Load references/components.md (~200 lines) when building shadcn-svelte 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.

shadcn-svelte-inertia