Elements

Snaps are built from 16 components organized into four categories. Every component lives in ui.elements as a named entry. The type field names the component; props carries its configuration; children names child element IDs; on binds event handlers.

"my-element": {
  "type": "text",
  "props": { "content": "Hello" }
}

Field components (input, slider, switch, toggle_group) collect user input. Their values are sent in the POST payload under inputs[name] when a submit action fires.

badge

Inline label with color and optional icon. Use for metadata, status indicators, and counts alongside content. "default" (filled) draws attention; "outline" is subtler. Pair with an icon for scannability.

{ "type": "badge", "props": { "label": "New" } }

{ "type": "badge", "props": { "label": "Live", "color": "green", "icon": "zap" } }

{
  "type": "badge",
  "props": { "label": "ERC-20", "variant": "outline", "color": "blue" }
}

button

Fires actions via on.press — the standard way to commit user input. Default variant is "secondary" (bordered); use "primary" (filled) for the main CTA, typically one per page. (cell_grid also fires actions, via on.press per cell.) See Actions for the full list of action types.

Variants

{
  "type": "button",
  "props": { "label": "Submit", "variant": "primary" },
  "on": {
    "press": { "action": "submit", "params": { "target": "https://my-snap.com/" } }
  }
}

{
  "type": "button",
  "props": { "label": "Open" },
  "on": {
    "press": { "action": "open_url", "params": { "target": "https://example.com" } }
  }
}

icon

Standalone icon from the curated set. Best as a visual accent inside item action slots or horizontal stacks. Avoid using icons as standalone content — pair with text or use inside a badge.

{ "type": "icon", "props": { "name": "star", "color": "amber" } }

Available Icons

image

HTTPS image with fixed aspect ratio. Use "16:9" for hero and banner images, "1:1" for avatars or thumbnails, "4:3" for general photos, and "9:16" for tall portrait content.

{
  "type": "image",
  "props": { "url": "https://example.com/photo.jpg", "aspect": "16:9" }
}

item

The go-to component for structured content rows: leaderboards, settings, key-value info. Mirrors shadcn Item: optional media renders on the left, title and description render in the content area, and children render in the actions slot on the right. Items are not interactive — don't use navigation-style affordances like chevron-right, arrow-right, or external-link that imply the row itself is clickable.

Variants

Media

Rendered on the left, before the item content, matching shadcn ItemMedia.

Children

Rendered in the actions slot (right side). Badges, buttons, and icons are all fair game — the item itself is not clickable, so pick trailing content that reads as content (status icon, badge, button), not navigation. Avoid chevron-right, arrow-right, or external-link on a plain item; they imply the row itself navigates.

"score": {
  "type": "item",
  "props": {
    "title": "Engagement Score",
    "description": "Based on 24h activity",
    "media": { "variant": "icon", "name": "trending-up", "color": "green" }
  },
  "children": ["score-badge"]
},
"score-badge": { "type": "badge", "props": { "label": "92", "color": "green" } }

"share": {
  "type": "item",
  "props": { "title": "Share this Snap", "description": "Pre-fill the composer" },
  "children": ["share-btn"]
},
"share-btn": {
  "type": "button",
  "props": { "label": "Share", "icon": "share" },
  "on": { "press": { "action": "compose_cast", "params": { "text": "Check out Snaps!" } } }
}

item_group

Wraps related items for visual grouping. Use separator: true for settings-style lists and border: true for card-like sections.

Children: item elements only.

"results": {
  "type": "item_group",
  "props": {},
  "children": ["r1", "r2", "r3"]
},
"r1": { "type": "item", "props": { "title": "First place", "description": "Alice" } },
"r2": { "type": "item", "props": { "title": "Second place", "description": "Bob" } },
"r3": { "type": "item", "props": { "title": "Third place", "description": "Charlie" } }

progress

Horizontal progress bar for completion, scores, or any bounded numeric value. Always uses the theme accent color. The label appears above the bar — use it for context like "78%" or "Level 3 of 5".

{ "type": "progress", "props": { "value": 65, "max": 100, "label": "Upload progress" } }

separator

Visual divider between logical sections of a page. Most snaps use 2-4 separators. Overusing them creates visual clutter.

{ "type": "separator", "props": {} }

stack

Layout container for arranging children. Every page starts with a vertical stack as root. Use horizontal stacks for button rows, badge groups, or side-by-side cards. Nested stack children of a horizontal stack flex as peers (equal share of the row by default), so you usually do not need columns just to place two sections side by side. justify: "between" is useful for navigation bars.

Gap

gap resolves to a different pixel value depending on direction. Horizontal stacks use a tighter scale because their children sit side-by-side and tend to be wider:

When gap is omitted, vertical stacks default to "md". Horizontal stacks pick a default based on column count — denser layouts get tighter gaps:

Column count is taken from columns when set, or inferred from button-row children. An explicit gap always wins — override the default when you have a deliberate visual reason (extra breathing room around a hero row, a visually compact toolbar, a hero+supporting-button pair where the loose lg default would feel disconnected).

"page": {
  "type": "stack",
  "props": {},
  "children": ["header", "content", "actions"]
}

"row": {
  "type": "stack",
  "props": { "direction": "horizontal", "gap": "sm" },
  "children": ["b1", "b2", "b3"]
}

text

The primary content element. Use weight: "bold" for headings and emphasis. Use size: "sm" for captions, timestamps, and secondary info.

{ "type": "text", "props": { "content": "Welcome to Snaps", "weight": "bold" } }

{
  "type": "text",
  "props": { "content": "Last updated 2 hours ago", "size": "sm", "align": "center" }
}

bar_chart

Horizontal bar chart for displaying ranked or comparative data. Each bar shows a label on the left, a colored fill bar, and a numeric value on the right. Use for poll results, leaderboards, or any ranked values.

Bar Object

{
  "type": "bar_chart",
  "props": {
    "bars": [
      { "label": "Poblano", "value": 42 },
      { "label": "Negro", "value": 38 },
      { "label": "Verde", "value": 15, "color": "green" }
    ]
  }
}

cell_grid

Grid of colored cells for pixel art, game boards, color pickers, and small data matrices. Cells are defined sparsely — only specify cells that have color or content.

There are two interaction modes, and they are mutually exclusive:

1. Press to act — leave select at "off" and bind on.press. Each press writes the pressed cell's value (or "row,col" if no value is set) to inputs[name] and fires the bound action (e.g. submit). No selection ring; cells behave like a grid of buttons.
2. Press to select — set select: "single" or "multiple". Each press accumulates selection state with a visual ring; nothing is posted. Pair with a separate button that submits the accumulated selection. Multi-select joins values with |.

Don't combine on.press with a non-"off" select mode — the auto-fire would defeat the accumulating selection. The component ignores on.press whenever select is on.

Events

Cell Object

Press to act — select: "off" (default) + on.press. Each press fires immediately:

{
  "type": "cell_grid",
  "props": {
    "name": "color_grid",
    "cols": 4,
    "rows": 4,
    "cells": [
      { "row": 0, "col": 0, "color": "red" },
      { "row": 0, "col": 3, "color": "blue" }
    ]
  },
  "on": {
    "press": { "action": "submit", "params": { "target": "https://my-snap.com/" } }
  }
}

Press to select — select: "single" or "multiple". Presses update the selection without posting; pair with a button that submits when the user is done:

{
  "type": "cell_grid",
  "props": {
    "cols": 4,
    "rows": 4,
    "cells": [
      { "row": 0, "col": 0, "color": "red" },
      { "row": 0, "col": 3, "color": "blue" },
      { "row": 1, "col": 1, "color": "green", "content": "X" },
      { "row": 3, "col": 3, "color": "purple" }
    ],
    "cellAspectRatio": "square",
    "select": "multiple"
  }
}

Value-bearing cells — when each cell represents a meaningful label (a calendar day, an alphabet letter, a region code), set value to keep the action handler clean. The handler receives the value directly instead of having to translate "row,col" back into a label:

{
  "type": "cell_grid",
  "props": {
    "name": "day",
    "cols": 7,
    "rows": 5,
    "cells": [
      { "row": 0, "col": 0, "value": "1", "content": "1" },
      { "row": 0, "col": 1, "value": "2", "content": "2" },
      { "row": 0, "col": 2, "value": "3", "content": "3" }
    ]
  },
  "on": {
    "press": { "action": "submit", "params": { "target": "https://my-snap.com/" } }
  }
}

The POST handler reads inputs.day as "3" directly — no row/col math.

input

Text or number input field for short free-text entry. Set type: "number" for numeric input (changes the mobile keyboard). Always provide a label for accessibility. Value is collected in POST inputs under name.

POST value: string.

{
  "type": "input",
  "props": { "name": "email", "label": "Email", "placeholder": "you@example.com" }
}

slider

Numeric range slider for bounded choices like ratings, quantities, or percentages. Always set meaningful min/max values and add a label so users know what they're adjusting. Value is collected in POST inputs under name.

POST value: number.

{
  "type": "slider",
  "props": {
    "name": "rating",
    "label": "Rating (1–10)",
    "min": 1,
    "max": 10,
    "showValue": true
  }
}

switch

Boolean toggle for binary preferences (on/off, yes/no). Good for settings-style pages — the label should describe the enabled state ("Enable notifications", not "Notifications toggle"). Value is collected in POST inputs under name.

POST value: boolean.

{
  "type": "switch",
  "props": { "name": "notifications", "label": "Enable notifications" }
}

toggle_group

Choice group for selecting between 2-6 discrete options. Prefer this over multiple buttons when the choices are parallel and exclusive. Use multiple: true for multi-select scenarios like tags or interests. Value is collected in POST inputs under name.

POST value: the selected option string (or string[] when multiple is true).

{
  "type": "toggle_group",
  "props": {
    "name": "plan",
    "label": "Choose a plan",
    "options": ["Free", "Pro", "Team"]
  }
}

{
  "type": "toggle_group",
  "props": {
    "name": "interests",
    "label": "Select interests",
    "multiple": true,
    "orientation": "vertical",
    "options": ["Dev", "Design", "Data", "Product"]
  }
}