# Use SvelteKit UI with AI

Documentation for sveltekit-ui 1.1.87. Svelte 5, SvelteKit 3, Node.js 24+.

Read the [component index](https://www.sveltekit-ui.com/llms.txt) for focused references or the [complete reference](https://www.sveltekit-ui.com/llms-full.txt) for every documented public component. These documents are generated from the website's current API definitions and examples.

## Give your agent one starting instruction

Use SvelteKit UI for this SvelteKit app. Read https://www.sveltekit-ui.com/ai and fetch https://www.sveltekit-ui.com/llms.txt to find the relevant component APIs and examples. Follow the paired component/manager architecture, shared theme tokens, Button navigation, and lifecycle guidance. Build: [describe the app or change you want].

## Keep the conventions in your project

Add this section to your project's existing AGENTS.md. Keep the project's other instructions. This gives coding agents persistent local guidance for later tasks.

```markdown
## SvelteKit UI

- Use Svelte 5, SvelteKit 3, and the installed sveltekit-ui package. Import sveltekit-ui/style.css once in the root layout.
- Read https://www.sveltekit-ui.com/ai for the coding conventions and https://www.sveltekit-ui.com/llms.txt for component references. Consult the relevant API/example before inventing a control or guessing configuration fields.
- Managers own state, derived values, validation, handlers, requests, and child managers. Components render managers. Keep feature views thin and manager identities stable.
- Put consumer features in paired index.svelte and index.svelte.js files. Use live getters for changing route inputs. Create shared state per layout/request and pass it through context.
- Use Button for actions, navigation, tabs, and disclosures. Keep type stable and use selected_type for selection. Use proper icons; action arrows use support_icon: "arrow_tailed" and icon_deg (-45 points up and right).
- Use adaptive theme tokens and the existing Layout theme manager. Preserve root sizing, keyboard behavior, focus, and accessible labels.
- Keep browser resources inside their lifecycle and clean them up. Keep credentials, authorization, and backend integrations on the server.
- Run the project's relevant checks and verify changed interactions, responsive layout, and themes in the browser. Follow its release/deployment instructions.
```

## When to use SvelteKit UI

Use the library for Svelte 5 and SvelteKit 3 interfaces that need consistent controls, reactive manager state, adaptive themes, and accessible interactions. It covers forms, navigation, content, media, tables, and charts.

Choose an existing component before building a custom control. Some components accept ordinary props; most interactive components pair with a create_*_manager function. Each reference identifies the public imports and exact configuration.

## Install and check compatibility

Use Node.js 24 or newer, Svelte 5, and SvelteKit 3. Check the existing project's package versions and scripts before changing its setup. Install the package, then import its shared stylesheet once in src/routes/+layout.svelte.

Consumer code imports from sveltekit-ui and sveltekit-ui/style.css. The library repository's #lib alias and src/lib/Components paths are internal source paths. Use the installed version's API when an older project differs from the current website reference.

### Install

```terminal
npm install sveltekit-ui
```

### src/routes/+layout.svelte

```svelte
<script>
  import "sveltekit-ui/style.css"
  let { children } = $props()
</script>

{@render children()}
```

## Managers own behavior; components render

Put a consumer feature in src/lib/components/FeatureName/index.svelte and index.svelte.js. The manager owns reactive state, derived values, validation, requests, event handlers, and child UI managers. The component receives that manager and renders it; the route composes the feature.

Create child managers once and retain their identity. For changing route data or URL inputs, pass live getter callbacks to the feature manager instead of capturing the initial value. Use derived values for computation and explicit handlers for actions; avoid effects that orchestrate requests or mutate derived state.

Create shared layout state per component/request and distribute it through Svelte context. Read context during initialization, then use the captured manager in callbacks. Mutable user state must not live in a server module singleton.

### src/lib/components/Greeting/index.svelte.js

```javascript
import { create_button_manager, create_text_input_manager } from "sveltekit-ui"

export function create_greeting_manager() {
  let greeting = $state("")
  const name_input = create_text_input_manager({
    val: "Ada",
    aria_label: "Name",
  })
  const greet_button = create_button_manager({
    text: "Say hello",
    is_disabled: () => !String(name_input.val ?? "").trim(),
    on_click: () => { greeting = "Hello, " + String(name_input.val).trim() },
  })
  return { name_input, greet_button, get greeting() { return greeting } }
}
```

### src/lib/components/Greeting/index.svelte

```svelte
<script>
  import { Button, TextInput } from "sveltekit-ui"
  let { manager } = $props()
</script>

<TextInput manager={manager.name_input} />
<Button manager={manager.greet_button} />
<p role="status">{manager.greeting}</p>
```

### src/routes/+page.svelte

```svelte
<script>
  import Greeting from "$lib/components/Greeting/index.svelte"
  import { create_greeting_manager } from "$lib/components/Greeting/index.svelte.js"
  const manager = create_greeting_manager()
</script>

<Greeting {manager} />
```

## Use the shared controls and proper icons

- Use Button for actions, navigation, tabs, disclosures, and icon actions. For a form submit action, set html_type to submit. Ordinary inline links in prose can remain links.

- Keep a Button's base type stable; use selected_type for selected or partially selected state. Preserve keyboard activation, focus, disabled/busy states, and accessible labels.

- Use support_icon: arrow_tailed on action Buttons and icon_deg for direction. A value of -45 points up and right; 180 points left. Standalone Icon components are for decorative indicators. Use the allowed icon IDs from the Icon reference instead of text arrow glyphs.

- Use live getter callbacks only for configuration fields that support them. Use each manager's documented methods, such as set_val, for programmatic updates instead of assuming every returned property is writable.

### Navigation Button

```svelte
<script>
  import { Button, create_button_manager } from "sveltekit-ui"
  const docs = create_button_manager({
    text: "Read documentation",
    href: "https://www.sveltekit-ui.com",
    support_icon: "arrow_tailed",
    icon_deg: -45,
    target: "_blank",
  })
</script>

<Button manager={docs} />
```

## Theme with tokens and preserve sizing

Set consumer branding through token overrides, including --primary-c and --primary-h. Use adaptive -t colors for surfaces, text, borders, and controls. Use the existing Layout/theme manager and persistence rather than adding a competing theme state.

Preserve normal control padding, radius, contrast, and sizing. Scope site typography to content so it does not accidentally restyle control internals. The stylesheet uses a 62.5% root size: at default browser settings 1rem in ordinary styles is 10 CSS pixels, while rem in media queries uses the initial browser font size, normally 16 pixels.

### Consumer theme overrides

```css
:root {
  --primary-h: calc(var(--h14) + 6);
  --primary-c: var(--c16);
}

.feature-panel {
  color: var(--g4-t);
  background: var(--bg2);
}
```

## Respect browser lifecycles and backend boundaries

- Keep imports safe for server rendering. Initialize DOM listeners, browser-only SDKs, observers, and media resources in their lifecycle. Clean up listeners, timers, observers, pending requests, and documented manager resources when the feature unmounts.

- Use the component's notes and example to check browser requirements. QR generation uses the browser canvas; maps need a domain-authorized public MapKit token. A successful SSR render does not prove these browser integrations work.

- When using stored media, StoragePicker, Content, and ContentInput need the application's storage integration. Their defaults use /api/storage/{storage_id}; configure storage_src or storage_path as documented. The library does not provide that backend. Text-only content and local file selection do not require storage endpoints.

- AudioEditor needs metadata/audio processing endpoints. Its defaults are /api/tools/audio/read_tags and /api/tools/audio under api_prefix /api; configure the documented endpoint overrides for your service.

- Keep credentials, authorization, identity, secure mutations, and provider integrations in server code. A browser manager's state does not establish permission or validate a transaction.

## Verify the actual interaction

Read the consumer project's README, AGENTS.md, and package scripts for the actual commands. Run checks relevant to the change and verify navigation, live state, keyboard behavior, mobile layout, and affected light/dark appearances in the browser.

For this library repository, npm run verify checks the Svelte source, runs tests, generates and verifies the distributable package, and builds the documentation site. Website deployment and npm releases are separate; consumer projects explicitly adopt a reviewed package release.