How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/vercel-labs/json-render --skill directivesBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
@json-render/directives
Pre-built custom directives for @json-render/core. Drop them into your catalog and renderer to add formatting, math, string manipulation, and i18n.
Quick Start
import { standardDirectives } from '@json-render/directives';
// Wire into prompt generation
const prompt = catalog.prompt({ directives: standardDirectives });
// Wire into the renderer (React example)
import { JSONUIProvider, Renderer } from '@json-render/react';
<JSONUIProvider registry={registry} directives={standardDirectives}>
<Renderer spec={spec} registry={registry} />
</JSONUIProvider>To add factory directives like createI18nDirective, spread the array:
import { standardDirectives, createI18nDirective } from '@json-render/directives';
const directives = [...standardDirectives, createI18nDirective(config)];Defining Custom Directives
Use defineDirective from @json-render/core:
import { defineDirective, resolvePropValue } from '@json-render/core';
import { z } from 'zod';
const doubleDirective = defineDirective({
name: '$double',
description: 'Double a numeric value.',
schema: z.object({
$double: z.unknown(),
}),
resolve(value, ctx) {
const resolved = resolvePropValue(value.$double, ctx);
return (resolved as number) * 2;
},
});Rules:
- Name must start with
$ - Name must not conflict with built-in keys (
$state,$cond,$computed,$template,$item,$index,$bindState,$bindItem) - Resolvers should call
resolvePropValueon sub-values to support composition
Built-in Directives
$format — Locale-aware value formatting
Formats values using Intl formatters. Supports date, currency, number, and percent.
{ "$format": "currency", "value": { "$state": "/cart/total" }, "currency": "USD" }
{ "$format": "date", "value": { "$state": "/user/createdAt" } }
{ "$format": "number", "value": 1234567, "notation": "compact" }
{ "$format": "percent", "value": 0.75 }
{ "$format": "date", "value": { "$state": "/post/createdAt" }, "style": "relative" }Fields: $format (date | currency | number | percent), value (any expression), locale? (string), currency? (string, default "USD"), notation? (string), style? ("relative" for relative dates), options? (extra Intl options).
$math — Arithmetic operations
{ "$math": "add", "a": { "$state": "/subtotal" }, "b": { "$state": "/tax" } }
{ "$math": "round", "a": 3.7 }Operations: add, subtract, multiply, divide, mod, min, max, round, floor, ceil, abs. Unary ops (round, floor, ceil, abs) only use a. Division by zero returns 0.
Fields: $math (operation enum), a? (first operand, default 0), b? (second operand, default 0).
$concat — String concatenation
{ "$concat": [{ "$state": "/user/firstName" }, " ", { "$state": "/user/lastName" }] }Fields: $concat (array of values to resolve and join into a string).
$count — Array/string length
{ "$count": { "$state": "/cart/items" } }Returns .length of arrays or strings, 0 for other types.
Fields: $count (value to count).
$truncate — Text truncation
{ "$truncate": { "$state": "/post/body" }, "length": 140, "suffix": "..." }Fields: $truncate (value to truncate), length? (max chars, default 100), suffix? (string, default "...").
$pluralize — Singular/plural forms
{ "$pluralize": { "$state": "/cart/itemCount" }, "one": "item", "other": "items", "zero": "no items" }Output: "3 items", "1 item", or "no items".
Fields: $pluralize (count value), one (singular label), other (plural label), zero? (zero label).
$join — Join array elements
{ "$join": { "$state": "/tags" }, "separator": ", " }Fields: $join (array to join), separator? (string, default ", ").
createI18nDirective — Internationalization factory
import { createI18nDirective } from '@json-render/directives';
const tDirective = createI18nDirective({
locale: 'en',
messages: {
en: { "greeting": "Hello, {{name}}!", "checkout.submit": "Place Order" },
es: { "greeting": "Hola, {{name}}!", "checkout.submit": "Realizar Pedido" },
},
fallbackLocale: 'en',
});Usage in specs:
{ "$t": "checkout.submit" }
{ "$t": "greeting", "params": { "name": { "$state": "/user/name" } } }Fields: $t (translation key), params? (interpolation parameters, values accept expressions).
Config: locale (current locale), messages (Record<locale, Record<key, string>>), fallbackLocale? (fallback when key missing).
Composition
Directives compose naturally — each resolver calls resolvePropValue on its inputs, so directives can wrap other directives or built-in expressions:
{
"$format": "currency",
"value": { "$math": "multiply", "a": { "$state": "/price" }, "b": { "$state": "/qty" } },
"currency": "USD"
}Resolves inside-out: $state reads from state, $math multiplies, $format formats as currency.
Wiring into Renderers
All four renderers (React, Vue, Svelte, Solid) accept directives on their provider and createRenderer output:
// Provider pattern
<JSONUIProvider registry={registry} directives={directives}>
<Renderer spec={spec} registry={registry} />
</JSONUIProvider>
// createRenderer pattern
const MyRenderer = createRenderer(catalog, components);
<MyRenderer spec={spec} directives={directives} />For prompt generation, pass the same array:
const prompt = catalog.prompt({ directives });Key Exports
| Export | Purpose |
|---|---|
formatDirective | $format directive definition |
mathDirective | $math directive definition |
concatDirective | $concat directive definition |
countDirective | $count directive definition |
truncateDirective | $truncate directive definition |
pluralizeDirective | $pluralize directive definition |
joinDirective | $join directive definition |
createI18nDirective | Factory for $t i18n directive |
standardDirectives | Array of all 7 non-factory directives |
I18nConfig | Type for i18n configuration |
