> ## Documentation Index
> Fetch the complete documentation index at: https://juo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Blocks
> Self-contained UI components with typed props and slots, described by a type-safe schema.
A **block** is a self-contained UI component. It has **props** to configure it and **slots** to compose it with other blocks. A type-safe **schema** describes both — driving TypeScript inference in the renderer.
What makes a block different from a regular component is that it can consume **services** from its surrounding [contexts](/docs/blocks/concepts/contexts) to read and manipulate live store data (subscriptions, customers, orders) without prop drilling.
## Anatomy of a block
Every block has four parts:
| Part | Purpose |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | Unique identifier (e.g. `"Button"`) used to reference the block from other blocks and from the registry. |
| **Schema** | JSON Schema that describes the block's `props` and `slots`. Drives type inference for the renderer. |
| **Initial value** | Function returning the default `props` / `slots` when the block is first instantiated. |
| **Renderer** | Function that takes a `BlockInstance` and returns an `HTMLElement` to mount. The framework boundary — implementations exist for plain DOM, [Vue](/docs/blocks/frameworks/vue), [React](/docs/blocks/frameworks/react), and [Preact](/docs/blocks/frameworks/preact). |
A block is **defined once** with `defineBlock`, **registered once** with `registerBlock`, and **instantiated many times** through `createBlockInstance`.
```ts theme={null}
import { defineBlock, registerBlock } from "@juo/blocks";
```
## A simple block
A button with one prop — a text label. The renderer creates a real DOM element and uses `effect()` to keep it in sync with `block.props`.
```ts theme={null}
import { defineBlock, registerBlock, effect, untracked } from "@juo/blocks";
import type { FromSchema, JSONSchema } from "json-schema-to-ts";
const schema = {
type: "object",
properties: {
props: {
type: "object",
properties: { label: { type: "string" } },
required: ["label"],
additionalProperties: false,
},
},
required: ["props"],
additionalProperties: false,
} as const satisfies JSONSchema;
export const ButtonBlock = defineBlock>("Button", {
group: "store",
schema,
initialValue: () => ({ props: { label: "Click me" } }),
renderer(block) {
const el = document.createElement("button");
effect(() => {
const { label } = block.props;
untracked(() => {
el.textContent = label;
});
});
return el;
},
});
registerBlock(ButtonBlock);
```
`as const satisfies JSONSchema` plus `FromSchema` keeps the schema and the renderer's prop types in sync — change the schema, the TS types update.
## A more advanced block
A card block with multiple typed props, nested slots, and a preset shown in the Editor's picker.
```ts theme={null}
import {
defineBlock,
registerBlock,
createBlockInstance,
effect,
untracked,
} from "@juo/blocks";
import { html, render } from "lit-html";
import type { FromSchema, JSONSchema } from "json-schema-to-ts";
const schema = {
type: "object",
properties: {
props: {
type: "object",
properties: {
variant: { enum: ["primary", "secondary", "ghost"] },
size: { enum: ["sm", "md", "lg"] },
showThumbnail: { type: "boolean" },
},
required: ["variant", "size", "showThumbnail"],
additionalProperties: false,
},
slots: {
type: "object",
properties: { header: {}, body: {}, actions: {} },
required: ["header", "body", "actions"],
additionalProperties: false,
},
},
required: ["props", "slots"],
additionalProperties: false,
} as const satisfies JSONSchema;
export const SubscriptionCardBlock = defineBlock>(
"SubscriptionCard",
{
group: "juo",
schema,
initialValue: () => ({
props: { variant: "primary", size: "md", showThumbnail: true },
slots: {
header: createBlockInstance("Text", { slots: { default: "Your plan" } }),
body: [],
actions: [
createBlockInstance("Button", { props: { label: "Manage" } }),
],
},
}),
presets: {
compact: {
label: "Compact",
description: "Smaller card with no thumbnail",
group: "Layouts",
state: { props: { variant: "ghost", size: "sm", showThumbnail: false } },
context: {},
},
},
renderer(block) {
const el = document.createElement("div");
effect(() => {
const { variant, size, showThumbnail } = block.props;
untracked(() => {
render(
html`
${showThumbnail ? html`
` : null}