artifacts.space/Docs
Sign in

Get started

  • Introduction
  • Quickstart
  • Client setup

Reference

  • MCP reference
  • Formats
  • Themes

Work together

  • Sharing, teams, and agents

Run it

  • Limits and quotas
  • Self-hosting

Earlier formats

  • JSON Render
  • Components

    Layout

    • Section
    • Stack
    • Grid
    • Card
    • Tabs
    • Accordion
    • Separator
    • Box

    Content

    • Heading
    • Text
    • Markdown
    • Code
    • Callout
    • Badge
    • List
    • Steps
    • Link
    • Quote
    • Icon
    • Avatar
    • AvatarGroup
    • Kbd
    • Rating

    Data

    • Table
    • Metric
    • Chart
    • KeyValue
    • Progress
    • Timeline
    • Diagram

    Planning

    • Board
    • Calendar

    Inputs

    • Checklist
    • Checkbox
    • Select
    • Switch
    • Slider
    • Button
    • Input
    • Textarea

    Media

    • Image
    • File
    • Placeholder
  • Dynamic props and actions
  • Charts
  • Section templates
  • Validation
  • Stout guarantees
  • Playground
  • Prompting your agent
artifacts.space
DocsSourceSign inCreate accountSupportPrivacyTerms

© 2026 Webrenew LLC

Components · Inputs

Button

A button. Its press event can run setState, toggleState, pushState, or removeState through on. It cannot load or send data. variant: default, outline, secondary, ghost, or danger (a solid fill in the danger tone, for an action that deletes or cannot be undone). size (sm, md, lg), fullWidth, disabled, and an icon by name (see Icon) at the start or the end (iconPosition); iconOnly shows the icon alone, with label as its name for screen readers. expanded tells screen readers whether what the button opens is open (a menu toggle, a "Show more"): read it from the same state the button flips, { "$state": "/open" }, which must hold true or false. pressed tells screen readers and shows that a toggle is on (Bold, a filter chip): read it from the state the button flips, { "$state": "/bold" }, which must hold true or false. A toggle takes variant outline, secondary, or ghost, which turn solid when pressed; default and danger refuse pressed, and a button takes pressed or expanded, not both.

ExamplesLink to this section

Set state on press
Choice: None yet
Show JSONHide JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["buttons", "answer"]
    },
    "buttons": {
      "type": "Stack",
      "props": { "direction": "horizontal", "gap": "sm" },
      "children": ["yes", "no"]
    },
    "yes": {
      "type": "Button",
      "props": { "label": "Approve" },
      "on": {
        "press": {
          "action": "setState",
          "params": { "statePath": "/answer", "value": "Approved" }
        }
      }
    },
    "no": {
      "type": "Button",
      "props": { "label": "Hold", "variant": "outline" },
      "on": {
        "press": {
          "action": "setState",
          "params": { "statePath": "/answer", "value": "On hold" }
        }
      }
    },
    "answer": {
      "type": "Badge",
      "props": { "label": { "$template": "Choice: ${/answer}" }, "tone": "info" }
    }
  },
  "state": { "answer": "None yet" }
}
Sizes and icons
Show JSONHide JSON
{
  "version": 1,
  "root": "box",
  "elements": {
    "box": {
      "type": "Box",
      "props": {
        "direction": "horizontal",
        "wrap": true,
        "align": "center",
        "gap": "sm"
      },
      "children": ["small", "medium", "large", "more", "off"]
    },
    "small": {
      "type": "Button",
      "props": {
        "label": "Filter",
        "size": "sm",
        "variant": "outline",
        "icon": "filter"
      }
    },
    "medium": {
      "type": "Button",
      "props": {
        "label": "Continue",
        "icon": "arrow-right",
        "iconPosition": "end"
      }
    },
    "large": {
      "type": "Button",
      "props": { "label": "Start free", "size": "lg" }
    },
    "more": {
      "type": "Button",
      "props": {
        "label": "More actions",
        "variant": "ghost",
        "icon": "dots",
        "iconOnly": true
      }
    },
    "off": {
      "type": "Button",
      "props": {
        "label": "Unavailable",
        "variant": "secondary",
        "disabled": true
      }
    }
  }
}
Full width
Show JSONHide JSON
{
  "version": 1,
  "root": "box",
  "elements": {
    "box": {
      "type": "Box",
      "props": { "maxWidth": "sm" },
      "children": ["wide"]
    },
    "wide": {
      "type": "Button",
      "props": { "label": "Create account", "fullWidth": true }
    }
  }
}
Open and close with one button

`expanded` reads the same state the button flips, so screen readers hear whether the list is open.

Show JSONHide JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["more", "list"]
    },
    "more": {
      "type": "Button",
      "props": {
        "label": "All plans",
        "variant": "outline",
        "icon": "chevron-down",
        "iconPosition": "end",
        "expanded": { "$state": "/open" }
      },
      "on": {
        "press": { "action": "toggleState", "params": { "statePath": "/open" } }
      }
    },
    "list": {
      "type": "List",
      "props": { "items": ["Starter", "Team", "Business"] },
      "visible": { "$state": "/open" }
    }
  },
  "state": { "open": false }
}
A toggle that stays pressed

`pressed` reads the same state the button flips, so one press turns Bold on, the button shows it, and screen readers hear it.

This line turns semibold while Bold is on.

Show JSONHide JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["bold", "sample"]
    },
    "bold": {
      "type": "Button",
      "props": {
        "label": "Bold",
        "variant": "outline",
        "size": "sm",
        "pressed": { "$state": "/bold" }
      },
      "on": {
        "press": { "action": "toggleState", "params": { "statePath": "/bold" } }
      }
    },
    "sample": {
      "type": "Text",
      "props": {
        "text": "This line turns semibold while Bold is on.",
        "weight": {
          "$cond": { "$state": "/bold" },
          "$then": "semibold",
          "$else": "normal"
        }
      }
    }
  },
  "state": { "bold": false }
}

PropsLink to this section

Generated from the zod schema the server validates with. Unknown props are ignored with a warning. Any prop can also be a dynamic value such as { "$state": "/path" }; it is checked again once it resolves.

PropTypeLimits and defaults
labelrequiredstringmax 60 chars
variant"default" | "outline" | "secondary" | "ghost" | "danger"—
size"sm" | "md" | "lg"—
fullWidthboolean—
icon"file-text" | "notes" | "notebook" | "book" | "book-2" | "writing" | "pencil" | "feather" | "quote" | "report" | "presentation" | "clipboard" | "archive" | "folder" | "paperclip" | "link" | "checklist" | "list-check" | "clipboard-list" | "clipboard-check" | "list-details" | "map" | "route" | "target" | "flag" | "compass" | "timeline" | "sitemap" | "hierarchy" | "gavel" | "scale" | "rocket" | "bulb" | "brain" | "search" | "microscope" | "flask" | "school" | "atom" | "language" | "code" | "terminal-2" | "brackets" | "git-branch" | "git-pull-request" | "git-merge" | "api" | "bug" | "puzzle" | "plug" | "tool" | "settings" | "adjustments" | "components" | "layout-dashboard" | "robot" | "package" | "database" | "server" | "cloud" | "cpu" | "table" | "chart-bar" | "chart-line" | "chart-pie" | "chart-dots" | "trending-up" | "stack-2" | "versions" | "calendar" | "calendar-event" | "clock" | "hourglass" | "alarm" | "refresh" | "lock" | "key" | "shield" | "shield-check" | "fingerprint" | "eye" | "users" | "user" | "message-circle" | "mail" | "bell" | "speakerphone" | "lifebuoy" | "circle-check" | "alert-triangle" | "info-circle" | "help-circle" | "ban" | "bolt" | "flame" | "sparkles" | "star" | "heart" | "trophy" | "home" | "building" | "briefcase" | "currency-dollar" | "shopping-cart" | "world" | "palette" | "photo" | "device-laptop" | "device-mobile" | "coffee" | "leaf" | "arrow-right" | "arrow-left" | "arrow-up-right" | "chevron-right" | "chevron-left" | "chevron-down" | "chevron-up" | "check" | "x" | "plus" | "minus" | "menu-2" | "dots" | "external-link" | "download" | "upload" | "send" | "player-play" | "trash" | "copy" | "filter" | "share" | "bookmark" | "tag" | "at" | "phone" | "map-pin" | "credit-card" | "gift" | "truck" | "thumb-up" | "login" | "logout" | "sun" | "moon" | "brand-github" | "brand-gitlab" | "brand-x" | "brand-linkedin" | "brand-youtube" | "brand-instagram" | "brand-facebook" | "brand-tiktok" | "brand-discord" | "brand-mastodon" | "brand-bluesky" | "brand-threads" | "brand-reddit" | "brand-twitch" | "brand-dribbble" | "brand-behance" | "brand-medium" | "brand-apple" | "brand-google" | "brand-windows" | "brand-android"—
iconPosition"start" | "end"—
iconOnlyboolean—
disabledboolean—
expandedboolean—
pressedboolean—

RulesLink to this section

  • press can run setState, toggleState, pushState, removeState, or validateForm. A button cannot load or send data.
  • toggleState flips the value at statePath between true and false, so one button opens and closes what a visible condition shows: { "action": "toggleState", "params": { "statePath": "/open" } }.
  • Variants: default, outline, secondary, ghost, danger. Sizes: sm, md, lg.
  • danger is for an action that deletes or cannot be undone: a solid fill in the danger tone. Its label reads on every Box surface and in every theme.
  • iconOnly needs an icon; the label is then what screen readers announce.
  • expanded says whether what the button opens is open (a menu toggle, a "Show more"). Read it from the same path the button flips: "expanded": { "$state": "/open" }. That path must hold true or false; any other value stops the button from being shown. Leave it off a button that opens nothing.
  • pressed says whether a toggle is on (Bold, a filter chip, a view switch). Read it from the path the button flips: "pressed": { "$state": "/bold" }. A toggle goes from quiet to solid when pressed, so it takes variant: "outline", "secondary", or "ghost": pressed, it is filled with the text color, with its label in the page color, on every surface. The default variant is solid already and is refused, and so is danger: a one-time action, not a state that stays on. A button takes pressed or expanded, never both.

Children and eventsLink to this section

Button is a leaf: it does not show children. Validation warns when a leaf has some; wrap them in a Stack or Card instead.

Events: press. Bind one with on to run a state action; see Actions.

Edit this page on GitHub
PreviousSliderNextInput

On this page

  • Examples
  • Props
  • Rules
  • Children and events