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

The only component that fires actions — bind them via on.press. Default variant is "secondary" (bordered); use "primary" (filled) for the main CTA, typically one per page. 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. Has a title, optional description, and an actions slot on the right side. Put badges, icons, or buttons in children for the action slot.

Variants

Children

Rendered in the actions slot (right side). Use for badges, icons, buttons, or any trailing content.

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

"nav": {
  "type": "item",
  "props": { "title": "Settings" },
  "children": ["nav-arrow"]
},
"nav-arrow": { "type": "icon", "props": { "name": "chevron-right", "color": "gray" } }

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. justify: "between" is useful for navigation bars.

"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. Use select to enable tap-to-select; taps write to POST inputs under name.

Cell Object

{
  "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" }
    ],
    "select": "multiple"
  }
}

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 } }

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"]
  }
}