# @humanspeak/svelte-json-view-lite — full reference

> Concatenated dump of every doc page under https://jsonview.svelte.page/docs.
> Each section is bounded by an HTML comment with the source URL,
> so agents can extract individual pages or cite a specific section.

---

<!-- Source: https://jsonview.svelte.page/docs/accessibility -->

# Accessibility

> WAI-ARIA treeview semantics, keyboard navigation, and SSR-safe IDs in @humanspeak/svelte-json-view-lite.

**Source:** [https://jsonview.svelte.page/docs/accessibility](https://jsonview.svelte.page/docs/accessibility)

---

`<JsonView>` implements the [WAI-ARIA Treeview pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) out of the box. The root renders as `role="tree"`, branches as `role="treeitem"`, and expand toggles as `role="button"` with matching `aria-expanded` and `aria-controls` wiring.

## DOM Shape

Simplified output for `{ user: { id: 1 } }`:

```html
<div role="tree">
  <ul role="group">
    <li role="treeitem" aria-expanded="true">
      <span role="button"
            aria-expanded="true"
            aria-controls="sv-abc-group"
            aria-label="collapse JSON">▾</span>
      <span>user</span>
      <ul id="sv-abc-group" role="group">
        <li role="treeitem">
          <span>id</span>: <span>1</span>
        </li>
      </ul>
    </li>
  </ul>
</div>
```

Every `aria-controls` is produced by Svelte 5's `$props.id()` — the same ID is emitted server-side and client-side, so hydration never breaks the assistive-tech contract.

## Keyboard Contract

When focus is on any expander button inside the tree:

| Key | Action |
|-----|--------|
| `Enter` / `Space` | Toggle the focused branch |
| `ArrowRight` | Expand the branch, or move focus to the first child if already expanded |
| `ArrowLeft` | Collapse the branch, or move focus to the parent if already collapsed |
| `ArrowDown` | Move focus to the next visible branch |
| `ArrowUp` | Move focus to the previous visible branch |
| `Home` | Move focus to the first branch in the tree |
| `End` | Move focus to the last visible branch |
| `Tab` / `Shift+Tab` | Move focus out of the tree (roving tabindex) |

The tree uses a **roving tabindex** — exactly one expander has `tabindex="0"` at a time, while the rest are `tabindex="-1"`. Clicking or focusing any expander updates the roving target, so tabbing into the tree always lands on the last-interacted branch.

## Screen Reader Labels

Each expander announces its state via `aria-label`. The default strings are:

```ts
{ collapseJson: 'collapse JSON', expandJson: 'expand JSON' }
```

Override for localization or terser wording by setting `ariaLabels` on your style map:

```svelte
<script lang="ts">
    import { JsonView, defaultStyles } from '@humanspeak/svelte-json-view-lite'

    const style = {
        ...defaultStyles,
        ariaLabels: { collapseJson: 'collapse', expandJson: 'expand' }
    }
</script>

<JsonView data={payload} {style} />
```

> **Note on `ariaLables` (sic).** `react-json-view-lite`'s original `StyleProps` shipped the typoed key. The Svelte port accepts either at runtime for parity but logs a `console.warn` when only the typoed key is present. Prefer `ariaLabels`; the alias is removed in 2.0.

## Click-to-Expand Considerations

When `clickToExpandNode` is enabled, labels become click targets but **do not** receive focus or a button role — the expander glyph remains the single keyboard-accessible activator. Keyboard users never see duplicated tab stops; mouse users get a larger hit target.

## SSR and Hydration

The tree is safe to render during SSR. Every `aria-controls` / `id` pair is produced by `$props.id()`, which is deterministic across server and client. No `Math.random()` or `Date.now()` — the IDs committed in the initial HTML match the ones rehydrated on the client.

## Testing with `@testing-library/svelte`

The tree's ARIA contract means queries work without implementation-specific selectors:

```ts
import { render, screen, fireEvent } from '@testing-library/svelte'
import { JsonView } from '@humanspeak/svelte-json-view-lite'

test('expands a branch on Enter', async () => {
    render(JsonView, { data: { nested: { inner: 1 } } })
    const expander = screen.getByRole('button', { name: /expand/i })
    await fireEvent.keyDown(expander, { key: 'Enter' })
    expect(expander).toHaveAttribute('aria-expanded', 'true')
})
```

## Known Limitations

- **Custom snippets.** Renderers you supply via snippet overrides are rendered inside the `<li role="treeitem">` cell; if you embed interactive elements (links, buttons) they add their own tab stops outside the roving tabindex. Keep snippet content non-interactive when possible or scope focus management yourself.
- **Text direction.** The arrow-key contract assumes LTR ("right opens, left closes"). RTL-aware swapping is not implemented.
- **Virtualization.** The tree is fully materialized — focus order matches DOM order. If you wrap the viewer in a virtualized list, the keyboard contract may not survive.

## Related

- [JsonView props](/docs/api/json-view) — `clickToExpandNode` and the interactive prop set
- [Types & snippets](/docs/api/types) — `AriaLabels` and the style shape

<!-- Source: https://jsonview.svelte.page/docs/api/json-view -->

# JsonView Props

> Complete prop reference for the JsonView component in @humanspeak/svelte-json-view-lite.

**Source:** [https://jsonview.svelte.page/docs/api/json-view](https://jsonview.svelte.page/docs/api/json-view)

---

`<JsonView>` accepts the full `Props` interface plus anything you'd normally pass to a `<div>`. Spread attributes (`class`, `id`, `data-*`, `aria-*`) land on the root container.

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'
</script>

<JsonView data={value} />
```

## Prop Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `object \| unknown[]` | — | **Required.** Object or array payload. Nested values can include strings, numbers, booleans, `Date`, `bigint`, functions, `null`, and `undefined`. |
| `style` | `Partial<StyleProps>` | `defaultStyles` | Classname map. Import `defaultStyles` or `darkStyles`, or pass a partial to override individual keys. |
| `shouldExpandNode` | `(level: number, value: unknown, field?: string) => boolean` | `allExpanded` | Predicate called for every expandable node. Return `true` to expand. Use the exported `allExpanded` / `collapseAllNested` helpers for the common cases. |
| `clickToExpandNode` | `boolean` | `false` | When `true`, clicking the field label (key) also toggles expand/collapse, not just the arrow. |
| `beforeExpandChange` | `(event: NodeExpandingEvent) => boolean` | — | Veto handler. Receives `{ level, value, field, newExpandValue }`. Return `false` to cancel the transition. |
| `compactTopLevel` | `boolean` | `false` | Render top-level primitives inline without the enclosing `{…}` wrapper. Useful when `data` is an array of mixed primitives. |
| `string` | `Snippet<[StringSnippetProps]>` | Default renderer | Override the renderer for string values. See [Snippet overrides](/docs/snippet-overrides). |
| `number` | `Snippet<[NumberSnippetProps]>` | Default renderer | Override the renderer for numbers. |
| `boolean` | `Snippet<[BooleanSnippetProps]>` | Default renderer | Override the renderer for booleans. |
| `null` | `Snippet<[NullSnippetProps]>` | Default renderer | Override the renderer for `null` values. |
| `undefined` | `Snippet<[UndefinedSnippetProps]>` | Default renderer | Override the renderer for `undefined` values. |
| `bigint` | `Snippet<[BigIntSnippetProps]>` | Default renderer | Override the renderer for `bigint` values. |
| `date` | `Snippet<[DateSnippetProps]>` | Default renderer | Override the renderer for `Date` instances. |
| `function` | `Snippet<[FunctionSnippetProps]>` | Default renderer | Override the renderer for function values. |
| `label` | `Snippet<[LabelSnippetProps]>` | Default renderer | Override the renderer for field labels (keys). |

## `data`

The root `data` prop is an object or array. Inside that tree, the viewer handles JSON values plus a few richer JavaScript leaves:

- **Plain objects and arrays** render as collapsible branches.
- **`Date`** renders with `toISOString()` by default; override with the `date` snippet.
- **`bigint`** renders as its decimal representation with the `n` suffix preserved in source.
- **`null` and `undefined`** render as red sentinels (color driven by `--sjv-null` / `--sjv-undefined`).
- **Functions** render as `function() { }` by default; override with the `function` snippet.

```svelte
<JsonView
    data={{
        name: 'Ada',
        joined: new Date('2024-01-15'),
        counter: 42n,
        notes: null
    }}
/>
```

## `shouldExpandNode`

The predicate runs once per expandable node on initial render. Subsequent toggling is user-driven.

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'

    // Expand everything up to depth 3, collapse arrays.
    const expand = (level: number, value: unknown) =>
        level < 3 && !Array.isArray(value)
</script>

<JsonView data={value} shouldExpandNode={expand} />
```

Two exports cover the common cases:

```ts
import { allExpanded, collapseAllNested } from '@humanspeak/svelte-json-view-lite'
```

- `allExpanded` — `() => true`
- `collapseAllNested` — `(level) => level === 0` (root only)

## `clickToExpandNode`

When `true`, the field label (key text) becomes a click target alongside the arrow. The style map's `clickableLabel` class is applied to affected labels.

```svelte
<JsonView data={payload} clickToExpandNode />
```

## `beforeExpandChange`

Called synchronously before an expansion state change. Return `false` to cancel.

```svelte
<script lang="ts">
    import type { NodeExpandingEvent } from '@humanspeak/svelte-json-view-lite'

    const veto = (event: NodeExpandingEvent) => {
        // Don't let users collapse the root.
        if (event.level === 0 && event.newExpandValue === false) return false
        return true
    }
</script>

<JsonView data={payload} beforeExpandChange={veto} />
```

## `compactTopLevel`

Useful for arrays of primitives where the wrapping `[…]` adds noise:

```svelte
<JsonView data={['one', 'two', 'three']} compactTopLevel />
```

Renders each element inline instead of nested under an array bracket.

## Snippet Props

All nine snippet props receive the same shape with a typed `value`. See [Snippet overrides](/docs/snippet-overrides) for the full recipe book.

```svelte
<JsonView data={payload}>
    {#snippet string({ value })}
        <a href={value} class="text-brand-500">{value}</a>
    {/snippet}
</JsonView>
```

## Spread Attributes

Everything in `HTMLAttributes<HTMLDivElement>` except `data` and `style` forwards to the root container:

```svelte
<JsonView
    data={payload}
    class="rounded-lg border p-4"
    id="api-response"
    aria-label="Server response"
/>
```

## Related

- [Types & snippets](/docs/api/types) — `StyleProps`, `SnippetOverrides`, event payloads in full
- [Themes & CSS variables](/docs/themes) — `--sjv-*` tokens
- [Accessibility](/docs/accessibility) — keyboard + ARIA contract

<!-- Source: https://jsonview.svelte.page/docs/api/types -->

# Types & Snippet Props

> Exported TypeScript types, style shape, and snippet prop interfaces for @humanspeak/svelte-json-view-lite.

**Source:** [https://jsonview.svelte.page/docs/api/types](https://jsonview.svelte.page/docs/api/types)

---

Every public type is exported from the package root. Import types with `import type`:

```ts
import type {
    Props,
    StyleProps,
    AriaLabels,
    SnippetOverrides,
    NodeExpandingEvent,
    StringSnippetProps,
    NumberSnippetProps,
    BooleanSnippetProps,
    NullSnippetProps,
    UndefinedSnippetProps,
    BigIntSnippetProps,
    DateSnippetProps,
    FunctionSnippetProps,
    LabelSnippetProps
} from '@humanspeak/svelte-json-view-lite'
```

## `Props`

Accepted by `<JsonView>`. See [JsonView props](/docs/api/json-view) for narrative documentation.

```ts
export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'data' | 'style'> {
    data: object | unknown[]
    style?: Partial<StyleProps>
    shouldExpandNode?: (level: number, value: unknown, field?: string) => boolean
    clickToExpandNode?: boolean
    beforeExpandChange?: (event: NodeExpandingEvent) => boolean
    compactTopLevel?: boolean
    string?: Snippet<[StringSnippetProps]>
    number?: Snippet<[NumberSnippetProps]>
    boolean?: Snippet<[BooleanSnippetProps]>
    null?: Snippet<[NullSnippetProps]>
    undefined?: Snippet<[UndefinedSnippetProps]>
    bigint?: Snippet<[BigIntSnippetProps]>
    date?: Snippet<[DateSnippetProps]>
    function?: Snippet<[FunctionSnippetProps]>
    label?: Snippet<[LabelSnippetProps]>
}
```

## `StyleProps`

Classname map consumed by the viewer. `defaultStyles` and `darkStyles` are ready-made instances.

```ts
export interface StyleProps {
    container: string
    basicChildStyle: string
    label: string
    clickableLabel: string
    nullValue: string
    undefinedValue: string
    numberValue: string
    stringValue: string
    booleanValue: string
    otherValue: string
    punctuation: string
    expandIcon: string
    collapseIcon: string
    collapsedContent: string
    childFieldsContainer: string
    noQuotesForStringValues?: boolean
    quotesForFieldNames?: boolean
    ariaLabels: AriaLabels
    /** @deprecated Use `ariaLabels`. Removed in 2.0. */
    ariaLables?: AriaLabels
    stringifyStringValues: boolean
}
```

### Key roles

| Key | Applies to |
|-----|------------|
| `container` | Outermost `<div>` around the tree |
| `basicChildStyle` | Wrapper around each leaf or expandable child |
| `label` | Field label (key) text |
| `clickableLabel` | Label variant when `clickToExpandNode` is on |
| `nullValue` / `undefinedValue` | `null` / `undefined` leaves |
| `numberValue` / `stringValue` / `booleanValue` | Matching primitive leaves |
| `otherValue` | `bigint`, `Date`, functions, and anything else |
| `punctuation` | Braces, brackets, colons, commas |
| `expandIcon` / `collapseIcon` | Arrow glyphs |
| `collapsedContent` | Summary shown for collapsed branches (`{…}` / `[…]`) |
| `childFieldsContainer` | `<ul role="group">` wrapping child fields |

### Boolean options

- `noQuotesForStringValues` — omit `"` around string leaves.
- `quotesForFieldNames` — wrap labels in `"`.
- `stringifyStringValues` — call `JSON.stringify` on strings so newlines and control characters appear as escape sequences.

## `AriaLabels`

Screen-reader labels applied to expander buttons.

```ts
export interface AriaLabels {
    collapseJson: string
    expandJson: string
}
```

Default (exported as `defaultAriaLabels`):

```ts
{ collapseJson: 'collapse JSON', expandJson: 'expand JSON' }
```

> **Note on `ariaLables` (sic).** The React source shipped this typo on the style shape. The Svelte port accepts either key at runtime and emits a `console.warn` if only the typoed key is set. Use `ariaLabels`; the typoed alias is scheduled for removal in 2.0.

## `SnippetOverrides`

Bag of optional per-type snippets. Every key matches a same-named prop on `<JsonView>`.

```ts
export interface SnippetOverrides {
    string?: Snippet<[StringSnippetProps]>
    number?: Snippet<[NumberSnippetProps]>
    boolean?: Snippet<[BooleanSnippetProps]>
    null?: Snippet<[NullSnippetProps]>
    undefined?: Snippet<[UndefinedSnippetProps]>
    bigint?: Snippet<[BigIntSnippetProps]>
    date?: Snippet<[DateSnippetProps]>
    function?: Snippet<[FunctionSnippetProps]>
    label?: Snippet<[LabelSnippetProps]>
}
```

## Snippet Prop Types

All value snippets share a single generic shape parameterized by the value's type:

```ts
export interface ValueSnippetProps<T> {
    value: T
    field?: string
    level: number
}
```

| Type alias | `value` type |
|------------|--------------|
| `StringSnippetProps` | `string` |
| `NumberSnippetProps` | `number` |
| `BooleanSnippetProps` | `boolean` |
| `NullSnippetProps` | `null` |
| `UndefinedSnippetProps` | `undefined` |
| `BigIntSnippetProps` | `bigint` |
| `DateSnippetProps` | `Date` |
| `FunctionSnippetProps` | `Function` |

`field` is the parent key (undefined at root and inside arrays). `level` is the depth (root = 0).

The `label` snippet gets a slightly different shape (no `value`):

```ts
export interface LabelSnippetProps {
    field: string
    level: number
}
```

## `NodeExpandingEvent`

Payload passed to `beforeExpandChange`. Return `false` to veto.

```ts
export interface NodeExpandingEvent {
    level: number
    value: unknown
    field?: string
    newExpandValue: boolean
}
```

## Related

- [JsonView props](/docs/api/json-view) — narrative prop docs
- [Snippet overrides](/docs/snippet-overrides) — worked examples for each snippet
- [Themes & CSS variables](/docs/themes) — how `StyleProps` maps to real CSS

<!-- Source: https://jsonview.svelte.page/docs/getting-started -->

# Getting Started

> Install and render your first JSON tree with @humanspeak/svelte-json-view-lite in under a minute.

**Source:** [https://jsonview.svelte.page/docs/getting-started](https://jsonview.svelte.page/docs/getting-started)

---

**@humanspeak/svelte-json-view-lite** is a Svelte 5 port of [react-json-view-lite](https://github.com/AnyRoad/react-json-view-lite). It renders any JSON-serializable value as a collapsible tree with keyboard navigation, SSR-stable IDs, CSS-variable theming, and typed per-type `Snippet` overrides — all with zero runtime dependencies.

## Installation

```bash
npm install @humanspeak/svelte-json-view-lite
```

```bash
pnpm add @humanspeak/svelte-json-view-lite
```

```bash
yarn add @humanspeak/svelte-json-view-lite
```

The package ships types, so TypeScript consumers need no additional `@types/*`.

## Quick Start

Import the component and pass any value as `data`:

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'

    const payload = {
        user: { id: 42, name: 'Ada Lovelace' },
        active: true,
        nextReview: null
    }
</script>

<JsonView data={payload} />
```

That's the whole API for the default case. The tree renders light-theme by default and respects `prefers-color-scheme` only through explicit theme swapping (see below).

## Dark Theme

Every public style token ships in two flavors. Swap them with a single prop:

```svelte
<script lang="ts">
    import { JsonView, darkStyles } from '@humanspeak/svelte-json-view-lite'
</script>

<JsonView data={payload} style={darkStyles} />
```

For a mode-aware site, bind the prop to your mode store:

```svelte
<script lang="ts">
    import { JsonView, defaultStyles, darkStyles } from '@humanspeak/svelte-json-view-lite'
    import { mode } from 'mode-watcher'

    const theme = $derived(mode.current === 'dark' ? darkStyles : defaultStyles)
</script>

<JsonView data={payload} style={theme} />
```

Prefer theming with CSS variables? Every color is exposed as a `--sjv-*` custom property — see [Themes & CSS variables](/docs/themes).

## Expansion Strategies

By default every node is collapsed except the root. Pass a `shouldExpandNode` predicate to change that:

```svelte
<script lang="ts">
    import { JsonView, allExpanded, collapseAllNested } from '@humanspeak/svelte-json-view-lite'
</script>

<!-- Fully expanded -->
<JsonView data={payload} shouldExpandNode={allExpanded} />

<!-- Only the root -->
<JsonView data={payload} shouldExpandNode={collapseAllNested} />

<!-- Custom: expand first two levels -->
<JsonView data={payload} shouldExpandNode={(level) => level < 2} />
```

## Next Steps

- [JsonView props](/docs/api/json-view) — every prop with defaults and types
- [Types & snippets](/docs/api/types) — `StyleProps`, `SnippetOverrides`, event payloads
- [Themes & CSS variables](/docs/themes) — the full `--sjv-*` token table
- [Snippet overrides](/docs/snippet-overrides) — replace any primitive's renderer
- [Accessibility](/docs/accessibility) — WAI-ARIA treeview + keyboard contract

<!-- Source: https://jsonview.svelte.page/docs/migration -->

# Migration

> Port react-json-view-lite usage to Svelte JSON View Lite with matching prop names and Svelte snippets.

**Source:** [https://jsonview.svelte.page/docs/migration](https://jsonview.svelte.page/docs/migration)

---

Svelte JSON View Lite intentionally follows `react-json-view-lite` closely. Most migrations are a component import change plus replacing React render functions with Svelte snippets when you need custom values.

## Install

```bash
npm i @humanspeak/svelte-json-view-lite
```

## Basic Component

```svelte
<script lang="ts">
    import { JsonView, defaultStyles } from '@humanspeak/svelte-json-view-lite'

    const data = { status: 'ok', count: 3 }
</script>

<JsonView {data} style={defaultStyles} />
```

## Prop Mapping

| React JSON View Lite | Svelte JSON View Lite | Notes |
| --- | --- | --- |
| `data` | `data` | Object or array JSON root. |
| `style` | `style` | Use `defaultStyles`, `darkStyles`, or a merged style map. |
| `shouldExpandNode` | `shouldExpandNode` | Same purpose: decide initial expansion by level and value. |
| `clickToExpandNode` | `clickToExpandNode` | Same interaction model. |
| `compactTopLevel` | `compactTopLevel` | Same root rendering option. |
| custom renderers | snippet props | Svelte snippets replace React render callbacks. |

## Snippet Override

```svelte
<script lang="ts">
    import { JsonView, defaultStyles } from '@humanspeak/svelte-json-view-lite'

    const data = { url: 'https://jsonview.svelte.page' }
</script>

{#snippet stringValue({ value }: { value: string })}
    {#if value.startsWith('https://')}
        <a href={value}>{value}</a>
    {:else}
        <span>{value}</span>
    {/if}
{/snippet}

<JsonView
    {data}
    style={defaultStyles}
    string={stringValue}
/>
```

## Deliberate Difference

The original React package includes a typoed `ariaLables` style key. Svelte JSON View Lite uses `ariaLabels`, while still honoring the typoed key at runtime with a warning for compatibility.

<!-- Source: https://jsonview.svelte.page/docs/snippet-overrides -->

# Snippet Overrides

> Replace the default renderer for any primitive, Date, bigint, function, or field label using Svelte 5 snippets.

**Source:** [https://jsonview.svelte.page/docs/snippet-overrides](https://jsonview.svelte.page/docs/snippet-overrides)

---

Snippet overrides are the one deliberate extension the Svelte port adds on top of `react-json-view-lite`'s API. Pass a `Snippet` as any of the nine type-keyed props and the viewer calls it instead of the built-in renderer for every matching value.

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'
</script>

<JsonView data={payload}>
    {#snippet string({ value })}
        <span class="text-brand-500">{value}</span>
    {/snippet}
</JsonView>
```

## Snippet Props

Every value snippet receives the same shape — just with a differently typed `value`:

```ts
interface ValueSnippetProps<T> {
    value: T
    field?: string  // parent key, or undefined at the root / inside arrays
    level: number   // depth (root = 0)
}
```

| Snippet | Fires for | `value` type |
|---------|-----------|--------------|
| `string` | String leaves | `string` |
| `number` | Number leaves | `number` |
| `boolean` | Boolean leaves | `boolean` |
| `null` | `null` leaves | `null` |
| `undefined` | `undefined` leaves | `undefined` |
| `bigint` | `bigint` leaves | `bigint` |
| `date` | `Date` instances | `Date` |
| `function` | Function values | `Function` |
| `label` | Every field label (key) | — (`{ field, level }`) |

See [Types & snippets](/docs/api/types) for the exported type aliases.

## Render URLs as links

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'

    const payload = {
        repo: 'https://github.com/humanspeak/svelte-json-view-lite',
        email: 'hello@humanspeak.com'
    }

    const isUrl = (s: string) => /^https?:\/\//.test(s)
</script>

<JsonView data={payload}>
    {#snippet string({ value })}
        {#if isUrl(value)}
            <a href={value} target="_blank" rel="noopener" class="text-brand-500 underline">
                {value}
            </a>
        {:else}
            "{value}"
        {/if}
    {/snippet}
</JsonView>
```

## Relative time for `Date` values

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'

    const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
    const relative = (d: Date) => {
        const diff = d.getTime() - Date.now()
        const days = Math.round(diff / 86400000)
        return rtf.format(days, 'day')
    }
</script>

<JsonView data={{ lastSeen: new Date(Date.now() - 3 * 86400000) }}>
    {#snippet date({ value })}
        <time datetime={value.toISOString()} title={value.toISOString()}>
            {relative(value)}
        </time>
    {/snippet}
</JsonView>
```

## Format large numbers

```svelte
<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'

    const fmt = new Intl.NumberFormat('en-US')
</script>

<JsonView data={{ views: 12_345_678, errors: 0 }}>
    {#snippet number({ value })}
        <span class="tabular-nums">{fmt.format(value)}</span>
    {/snippet}
</JsonView>
```

## Badge booleans

```svelte
<JsonView data={{ active: true, verified: false }}>
    {#snippet boolean({ value })}
        <span
            class="rounded px-1.5 py-0.5 text-xs font-medium"
            class:bg-green-100={value}
            class:text-green-900={value}
            class:bg-red-100={!value}
            class:text-red-900={!value}
        >
            {value ? 'yes' : 'no'}
        </span>
    {/snippet}
</JsonView>
```

## Field-scoped rendering

The `field` prop lets you key behavior off the parent label:

```svelte
<JsonView data={{ email: 'ada@example.com', bio: 'Mathematician.' }}>
    {#snippet string({ value, field })}
        {#if field === 'email'}
            <a href={`mailto:${value}`}>{value}</a>
        {:else}
            "{value}"
        {/if}
    {/snippet}
</JsonView>
```

`field` is `undefined` at the root and inside array elements. `level` is the depth — useful for nested-specific styling.

## Custom label renderer

The `label` snippet replaces the default key rendering. It receives `{ field, level }` and no `value`:

```svelte
<JsonView data={payload}>
    {#snippet label({ field, level })}
        <span class="font-mono text-muted-foreground" class:text-brand-500={level === 0}>
            {field}
        </span>
    {/snippet}
</JsonView>
```

## Mixing themes and snippets

Snippets only replace the value cell. The surrounding container, punctuation, and field label continue to use `StyleProps` classes and `--sjv-*` tokens. Combine both for full theming:

```svelte
<JsonView data={payload} style={darkStyles}>
    {#snippet string({ value })}
        <em>{value}</em>
    {/snippet}
</JsonView>
```

## Related

- [JsonView props](/docs/api/json-view) — every snippet listed alongside the other props
- [Types & snippets](/docs/api/types) — exported prop types for each snippet
- [Themes & CSS variables](/docs/themes) — theming the parts snippets don't touch

<!-- Source: https://jsonview.svelte.page/docs/themes -->

# Themes & CSS Variables

> Swap built-in light and dark themes or drive every color through CSS custom properties with @humanspeak/svelte-json-view-lite.

**Source:** [https://jsonview.svelte.page/docs/themes](https://jsonview.svelte.page/docs/themes)

---

The library ships two classname maps — `defaultStyles` (light) and `darkStyles` — and exposes every color as a `--sjv-*` CSS custom property so you can retheme without swapping the `style` prop.

## Built-in Themes

```svelte
<script lang="ts">
    import { JsonView, defaultStyles, darkStyles } from '@humanspeak/svelte-json-view-lite'
</script>

<!-- Light (default) -->
<JsonView data={payload} />

<!-- Dark -->
<JsonView data={payload} style={darkStyles} />
```

Both exports conform to `StyleProps`. Spread them to patch individual keys:

```svelte
<JsonView
    data={payload}
    style={{ ...defaultStyles, quotesForFieldNames: true, stringifyStringValues: true }}
/>
```

## CSS Variable Tokens

Every color used by the viewer is declared on the container element as a `--sjv-*` custom property. Overriding any token cascades to every descendant that reads it.

| Token | Applies to | Light default | Dark default |
|-------|------------|---------------|--------------|
| `--sjv-background` | Container background | `#eee` | `rgb(0, 43, 54)` |
| `--sjv-label` | Field labels (keys) | `#000000` | `rgb(253, 246, 227)` |
| `--sjv-punctuation` | Braces, brackets, colons, commas | `#000000` | `rgb(253, 246, 227)` |
| `--sjv-string` | String values | `rgb(42, 63, 60)` | `rgb(203, 75, 22)` |
| `--sjv-number` | Number values | `#0b75f5` | `rgb(211, 54, 130)` |
| `--sjv-boolean` | Boolean values | `rgb(70, 144, 56)` | `rgb(174, 129, 255)` |
| `--sjv-null` | `null` values | `#df113a` | `rgb(129, 181, 172)` |
| `--sjv-undefined` | `undefined` values | `#df113a` | `rgb(129, 181, 172)` |
| `--sjv-other` | `bigint`, `Date`, functions | `#43413d` | `rgb(38, 139, 210)` |
| `--sjv-expander` | Arrow glyphs + collapsed summary | `#000000` | `rgb(253, 246, 227)` |

## Global Overrides

Set tokens on `:root` to retheme every instance on the page:

```css
:root {
    --sjv-string: lavender;
    --sjv-number: var(--brand-500);
    --sjv-background: transparent;
}
```

Because the defaults are declared on the container (not fallbacks on `var()`), inheritance from `:root` alone does **not** win against the per-container declarations. Use a selector with higher specificity, or target the tree element directly:

```css
[role='tree'] {
    --sjv-background: transparent;
}
```

## Per-Instance Overrides

Scope custom tokens to one viewer with a wrapping class. The library's container selector has specificity `(0,1,0)`; anything with `(0,2,0)` or higher wins without `!important`:

```svelte
<div class="payload-view">
    <JsonView data={payload} />
</div>

<style>
    .payload-view :global([role='tree']) {
        --sjv-background: transparent;
        --sjv-label: var(--color-foreground);
        --sjv-string: #f59e0b;
        --sjv-number: var(--color-brand-500);
    }
</style>
```

This is exactly how the landing page's live playground tracks light and dark modes — it maps `--sjv-*` tokens to the site's design-system variables.

## Dark Mode with `mode-watcher`

If you use [`mode-watcher`](https://www.npmjs.com/package/mode-watcher), derive the style prop from the current mode:

```svelte
<script lang="ts">
    import { JsonView, defaultStyles, darkStyles } from '@humanspeak/svelte-json-view-lite'
    import { mode } from 'mode-watcher'

    const theme = $derived(mode.current === 'dark' ? darkStyles : defaultStyles)
</script>

<JsonView data={payload} style={theme} />
```

Or skip the prop swap entirely and let CSS variables switch based on a root class:

```css
:root { --sjv-background: #eee; }
.dark { --sjv-background: #0f172a; }
```

## Boolean Style Options

`StyleProps` has three booleans that affect rendering regardless of which palette you pick:

| Option | Effect |
|--------|--------|
| `noQuotesForStringValues` | Omits the `"` around string leaves |
| `quotesForFieldNames` | Wraps field labels in `"` |
| `stringifyStringValues` | Passes string values through `JSON.stringify` so control characters render as escapes |

```svelte
<JsonView
    data={payload}
    style={{ ...defaultStyles, quotesForFieldNames: true, noQuotesForStringValues: true }}
/>
```

## Related

- [Types & snippets](/docs/api/types) — the full `StyleProps` shape
- [Snippet overrides](/docs/snippet-overrides) — when theming isn't enough and you need a custom renderer