Buttons

Buttons are button components in ui.elements. They are not a separate top-level array — they are elements like any other, placed wherever makes sense in the layout.

A button fires an action when tapped. Actions are bound via the on.press field. See Actions for the full list.

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

Button Properties

Prop	Type	Required	Default	Description
`label`	string	Yes		Button text. Max 30 chars
`variant`	string	No	`"secondary"`	Visual style (see below)
`icon`	IconName	No		Leading icon. See icon set

Variants

Variant	Description
`primary`	Solid accent background, white text — use for the primary CTA
`secondary`	Accent-colored border, transparent fill

Button Layout

Place buttons inside a stack component. Use direction: "horizontal" for a row of buttons, or the default "vertical" for a stacked column.

"actions": {
  "type": "stack",
  "props": { "direction": "horizontal", "gap": "sm" },
  "children": ["btn-yes", "btn-no"]
},
"btn-yes": {
  "type": "button",
  "props": { "label": "Yes", "variant": "primary" },
  "on": { "press": { "action": "submit", "params": { "target": "https://my-snap.com/yes" } } }
},
"btn-no": {
  "type": "button",
  "props": { "label": "No" },
  "on": { "press": { "action": "submit", "params": { "target": "https://my-snap.com/no" } } }
}

Action Types

The four most common actions on buttons:

Action	Behavior
`submit`	POST to the snap server, receive the next page
`open_url`	Open a URL in the browser
`open_mini_app`	Open a URL as a Farcaster mini app
client actions	`view_cast`, `view_profile`, `compose_cast`, `send_token`, etc.

See Actions for parameters and examples for each type.

Target URLs

For submit, open_url, and open_mini_app, params.target is an HTTPS URL in production.

For local development, http:// is valid only when the host is loopback: localhost, 127.0.0.1, or IPv6 loopback ([::1] / ::1).

Input Data in POST Requests

When a submit action fires, the client collects values from all field components on the current page and includes them in the POST body under inputs.

Component	POST value
`input`	string
`slider`	number
`switch`	boolean
`toggle_group` (single)	string
`toggle_group` (multiple)	string[]

Field components without a user interaction are included with their default values.

{
  "fid": 12345,
  "inputs": {
    "username": "alice",
    "rating": 7,
    "notifications": true,
    "plan": "Pro"
  },
  "button_index": 0,
  "timestamp": 1717200000
}

Timeout: The client waits up to 5 seconds. If the server doesn't respond, an error is shown on the current page and the user can retry.