@humanspeak/svelte-json-view-lite

Fast, tiny JSON tree viewer for Svelte 5 — a port of react-json-view-lite (MIT © 2024 AnyRoad) with runes, SSR, per-type snippet overrides, and zero runtime dependencies.

Features

• Svelte 5 runes throughout ($props, $state, $derived, $effect).
• Drop-in API parity with react-json-view-lite: same prop names, themes, and strategy helpers.
• Typed Snippet overrides for values, labels, row wrappers, expanders, collapsed indicators, and child groups — including declarative animation.
• SSR-safe: uses $props.id() for stable aria-controls linkage across server/client.
• Keyboard accessible: roving tabindex + ArrowUp/ArrowDown/ArrowLeft/ ArrowRight navigation, full WAI-ARIA treeview semantics.
• Ships built-in light and dark themes via CSS Modules.

Installation

npm i -S @humanspeak/svelte-json-view-lite
# or
pnpm add @humanspeak/svelte-json-view-lite

Basic usage

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

    const data = {
        name: 'Ada Lovelace',
        tags: ['admin', 'beta'],
        active: true,
        joined: new Date('2024-01-15')
    }
</script>

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

Props

| Prop | Type | Default | Description | | -------------------------------------------- | ---------------------------------------- | --------------- | ------------------------------------------------------------------------------------ | | data | object \| unknown[] | — | The JSON-shaped value to render. | | style | Partial<StyleProps> | defaultStyles | Classname-map that themes every slot. | | shouldExpandNode | (level, value, field?) => boolean | allExpanded | Initial-expand strategy per node. | | clickToExpandNode | boolean | false | When true, clicking the field label also toggles the node. | | clickToExpandSummary | boolean | true | Allow collapsed summary/punctuation clicks to expand. Chevron behavior is unchanged. | | beforeExpandChange | (event: NodeExpandingEvent) => boolean | — | Return false to veto an expand/collapse transition. | | childrenTransition | ChildrenTransition | — | Optional Svelte transition for child groups; updates are instant when omitted. | | compactTopLevel | boolean | false | Spread root-object entries instead of nesting them under a single root expander. | | row, expander, collapsed, childGroup | Typed Snippet | — | Replace structural rendering while retaining expansion and keyboard behavior. | | string, number, ... | Snippet<[{ value, field?, level }]> | — | Optional per-type renderer overrides. See Snippet overrides. |

Any additional HTML attributes (aria-*, data-*, id, class, etc.) are forwarded onto the root <div role="tree">.

Themes

Two themes ship out of the box:

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

<JsonView data={json} style={darkStyles} />

Override individual slots by spreading:

<JsonView
    {data}
    style={{
        ...defaultStyles,
        stringValue: 'my-custom-string-class',
        punctuation: 'my-custom-punctuation-class'
    }}
/>

For viewers that display each value in its own row, set the optional style.hideCommas flag:

<JsonView {data} style={{ hideCommas: true }} />

It defaults to false in both themes, preserving separator commas. When true, separator commas are omitted from primitive, object, and array rows, including expanded, collapsed, and empty containers. Brackets, commas inside string values, and the underlying data are unchanged. It also applies when using row or value snippets; punctuation supplied by your own snippets remains under your control.

Animate expansion

Pass an optional childrenTransition function to animate the live child group when a node opens or closes. It receives the group's HTMLElement and returns a Svelte TransitionConfig. The transition is local and reversible: closing a parent slides the whole subtree together, and clicking again reverses it. No animation dependency is added to the viewer.

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

    const slideChildren = (node: HTMLElement) =>
        slide(node, { duration: prefersReducedMotion.current ? 0 : 240 })
</script>

<JsonView {data} childrenTransition={slideChildren} />

Exiting children remain visible until the transition ends, but are hidden from assistive technology and skipped by keyboard navigation. Without this prop, expansion and collapse remain instant.

Structural snippets

Use row, expander, collapsed, and childGroup to customize the tree’s structure. The viewer owns expansion, veto callbacks, keyboard navigation, and focus. Your snippets own presentation, including declarative Svelte Motion components.

| Snippet | Receives | Responsibility | | ------------ | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | row | id, field, value, level, isContainer, expanded, attrs, children | Spread attrs on the row root; render children() once. | | expander | field, value, level, expanded, count, isArray, hovered, focused, focusVisible | Render noninteractive content inside the viewer’s accessible button. Replaces the default glyph. | | collapsed | field, value, level, expanded, count, isArray | Render a persistent indicator before the closing bracket; animate it to zero width when expanded. The viewer handles clicks when collapsed unless clickToExpandSummary={false}. | | childGroup | Container state plus attrs, children | Spread attrs on the group and render children() inside it. Own conditional rendering and any exit animation. |

For clickable copy rows, set clickToExpandSummary={false} and attach a normal onclick handler to your row snippet. Chevron clicks and arrow-key navigation still work; field-label expansion remains controlled by clickToExpandNode. The viewer wraps custom collapsed content in an inline-flex span, so whitespace emitted around snippet elements cannot add a gap before the closing bracket, even with a custom punctuation class. Snippets still control their own intentional spacing. Use focusVisible to animate a caret for keyboard focus; focused also includes mouse focus. The Motion + Tailwind example demonstrates these patterns.

<script lang="ts">
    import { JsonView } from '@humanspeak/svelte-json-view-lite'
    import { AnimatePresence, MotionUl, useReducedMotion } from '@humanspeak/svelte-motion'

    const reducedMotion = useReducedMotion()
</script>

<JsonView {data}>
    {#snippet childGroup({ expanded, attrs, children })}
        <AnimatePresence present={expanded} initial={false}>
            {#snippet child()}
                <MotionUl
                    {...attrs}
                    initial={{ height: 0 }}
                    animate={{ height: 'auto' }}
                    exit={{ height: 0 }}
                    transition={{ duration: reducedMotion.current ? 0 : 0.24 }}
                    style={{ overflow: 'hidden' }}
                >
                    {@render children()}
                </MotionUl>
            {/snippet}
        </AnimatePresence>
    {/snippet}
</JsonView>

childGroup stays mounted as expansion changes, so it can retain real child nodes during exits. Its attrs preserve the group ID, ARIA role, hidden state, and inert state. Child values stay lazy until first expansion. A supplied childGroup owns animation instead of childrenTransition. Existing value and label snippets compose with all four structural snippets.

See the Tailwind + Svelte Motion example for all four together. Svelte Motion is an optional application dependency.

Retheme via CSS variables

Every color in the built-in themes is declared as a CSS custom property on the root container, so you can tweak one or more colors without swapping the entire style prop or bringing your own classname map. The variables all live under the --sjv-* namespace:

| Variable | Default (light) | Default (dark) | Applies to | | ------------------- | ------------------ | -------------------- | ------------------------------------------ | | --sjv-background | #eee | rgb(0, 43, 54) | Root container background | | --sjv-label | #000000 | rgb(253, 246, 227) | Field label text | | --sjv-punctuation | #000000 | rgb(253, 246, 227) | Brackets, colons, commas | | --sjv-string | rgb(42, 63, 60) | rgb(203, 75, 22) | String values | | --sjv-number | #0b75f5 | rgb(211, 54, 130) | Number & BigInt values | | --sjv-boolean | rgb(70, 144, 56) | rgb(174, 129, 255) | Boolean values | | --sjv-null | #df113a | rgb(129, 181, 172) | null literal | | --sjv-undefined | #df113a | rgb(129, 181, 172) | undefined literal | | --sjv-other | #43413d | rgb(38, 139, 210) | Dates, functions, symbols, etc. | | --sjv-expander | #000000 | rgb(253, 246, 227) | ▸ / ▾ icons and collapsed ... marker |

Global override — applies to every JsonView on the page:

:root {
    --sjv-string: lavender;
    --sjv-number: #ff71ce;
}

Scoped override — target one component (or a subtree):

<div class="vaporwave">
    <JsonView {data} style={defaultStyles} />
</div>

<style>
    .vaporwave :global(div[role='tree']) {
        --sjv-background: #2b1055;
        --sjv-string: #01cdfe;
        --sjv-number: #05ffa1;
        --sjv-boolean: #b967ff;
    }
</style>

Per-instance override — forward inline styles via the root div (ARIA attrs and style on <JsonView> are spread onto the wrapper):

<JsonView {data} style={defaultStyles} style:--sjv-number="tomato" />

All three patterns work with either defaultStyles or darkStyles — the variables are defined on both container classes with theme-specific fallback defaults, so one override applies to whichever theme is active.

See the /test/css-variables playground route for a live example.

Snippet overrides

Unlike the React lib, svelte-json-view-lite exposes typed Snippet overrides for every primitive type plus the field label. Each snippet receives { value, field?, level }; omit the snippet to fall through to the default rendering.

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

    const data = {
        joined: new Date('2024-01-15'),
        docs: 'https://example.com/docs'
    }

    function relative(d: Date): string {
        const days = Math.round((d.getTime() - Date.now()) / 86_400_000)
        return new Intl.RelativeTimeFormat('en').format(days, 'day')
    }
</script>

<JsonView {data}>
    {#snippet date({ value }: DateSnippetProps)}
        <span title={value.toISOString()}>{relative(value)}</span>
    {/snippet}
    {#snippet string({ value }: StringSnippetProps)}
        {#if /^https?:/.test(value)}
            <a href={value}>{value}</a>
        {:else}
            "{value}"
        {/if}
    {/snippet}
</JsonView>

Available snippets: string, number, boolean, null, undefined, bigint, date, function, label. Their typed prop interfaces (StringSnippetProps, LabelSnippetProps, etc.) are all exported from the package root.

Expand strategies

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

<!-- expand only the root, collapse every child -->
<JsonView {data} shouldExpandNode={collapseAllNested} />

<!-- expand everything (default) -->
<JsonView {data} shouldExpandNode={allExpanded} />

<!-- custom: expand up to depth 2 -->
<JsonView {data} shouldExpandNode={(level) => level < 2} />

Migrating from react-json-view-lite

The Svelte API preserves the shared React prop names and adds these extensions:

| React | Svelte | | --------------------------- | ---------------------------------------------------------- | | style.ariaLables (typoed) | style.ariaLabels (fixed; typo still honored with a warn) | | — (not supported) | Structural and per-type Snippet overrides | | — | style.hideCommas to omit row separators | | — | clickToExpandSummary to control summary expansion |

Everything else — style, clickToExpandNode, compactTopLevel, beforeExpandChange, shouldExpandNode, defaultStyles, darkStyles, allExpanded, collapseAllNested — works identically.

Accessibility

• Root element has role="tree" with aria-label="JSON view" (overridable).
• Every expandable node is a role="treeitem" with live aria-expanded and, when open, aria-controls pointing at its child <ul role="group">.
• Keyboard support follows the WAI-ARIA 1.2 Treeview pattern:
  • ArrowRight expands, ArrowLeft collapses.
  • ArrowDown / ArrowUp move focus between expanders (wrapping).
  • Roving tabindex keeps only one expander in the tab order.

Development

pnpm install
pnpm dev          # launch SvelteKit playground on :8233
pnpm check        # svelte-check
pnpm lint         # Prettier + ESLint through Trunk
pnpm lint:fix     # apply formatting and lint fixes through Trunk
pnpm test         # vitest + coverage
pnpm build        # vite build + svelte-package + publint

The lint commands require the Trunk CLI. They honor the same trunk-ignore comments as CI and the pre-commit hook. ESLint checks source, unit tests, browser tests, and tooling; library production code also gets type-aware Promise checks and a modified cyclomatic complexity limit of 15.

Svelte 5 ecosystem

Part of the Humanspeak family of runes-native Svelte 5 packages:

| Package | Description | | --- | --- | | @humanspeak/svelte-markdown | Runtime markdown renderer for Svelte | | @humanspeak/svelte-virtual-list | Virtual scrolling for Svelte | | @humanspeak/svelte-motion | Framer Motion for Svelte 5 | | @humanspeak/svelte-headless-table | Headless data tables for Svelte | | @humanspeak/svelte-virtual-chat | Virtual chat viewport for Svelte 5 | | @humanspeak/svelte-diff | Diff comparison for Svelte | | @humanspeak/svelte-purify | HTML sanitisation for Svelte | | @humanspeak/memory-cache | In-memory cache for TypeScript | | @humanspeak/svelte-json-view-lite — this package | JSON tree viewer for Svelte 5 | | @humanspeak/svelte-scoped-props | Scoped class props for Svelte |

License

MIT © Humanspeak, Inc.

Credits

Made with ❤️ by Humanspeak