Skip to main content
Buttons trigger actions and communicate intent. The variant parameter signals what kind of action the button performs, while size controls its dimensions.

​
Basic Usage

The label can be passed as a positional argument or as a keyword (label="Save Changes").

​
Variants

Each variant communicates a different intent to the user:

​
Sizes

The size prop scales a button’s padding and text from xs through lg. Reach for the smaller sizes (xs, sm) when buttons are packed into dense surfaces like toolbars, table rows, or inline controls, and the larger lg when you want a primary call to action to stand out as the focal point of a screen.

​
With Icons

Buttons accept an icon prop (any lucide icon name in kebab-case). The icon renders before the label text.

​
Icon Sizes

Square buttons optimized for single icons. Use icon with an icon-size variant for icon-only buttons.

​
Button Type

Inside a Form, buttons default to type="submit", which triggers form submission on click. Set button_type="button" for actions that should not submit the form, like cancel or close buttons.
The three standard HTML button types are available: "submit" (default in forms), "button" (no form behavior), and "reset" (clears the form).

​
Disabled State

Set disabled=True to signal that an action is unavailable right now and to block clicks until conditions change. The button dims and stops responding to interaction, which is the right state for a submit button while a form is incomplete or an operation that can’t run until a prerequisite is met.

​
Custom Styling

Every component accepts css_class for additional Tailwind CSS classes. When your classes target the same CSS property as a built-in style (like rounded-full vs the default rounded-md), the built-in class is automatically removed so your override wins cleanly:

​
API Reference

Button Parameters

​
str
required
Button text. Can be passed as a positional argument.
​
str | None
default:"None"
Lucide icon name in kebab-case (e.g., "arrow-right", "trash-2"). Browse icons at lucide.dev/icons.
​
str
default:"default"
Visual style: "default", "destructive", "outline", "secondary", "ghost", "link", "success", "warning", "info".
​
str
default:"default"
Button dimensions: "default", "xs", "sm", "lg", "icon", "icon-xs", "icon-sm", "icon-lg".
​
str | None
default:"None"
HTML button type: "submit" (default in forms), "button" (no form submit), or "reset". Use "button" for cancel/close actions inside a Form.
​
bool | str
default:"False"
Whether the button is non-interactive. Accepts a template expression like "{{ not $item.name }}" for conditional disabling.
​
Action | list[Action] | None
default:"None"
Action(s) to run when the button is clicked. Pass a list to sequence them; server actions like CallTool take their own on_success/on_error callbacks for follow-ups.
​
str | None
default:"None"
Additional Tailwind CSS classes appended to the component’s built-in styles.

​
Protocol Reference

Button
For the complete protocol schema, see Button.