Struct Button 

pub struct Button { /* private fields */ }

An element that creates a button with a label and optional icons.

Common buttons:

• Label, Icon + Label: Button (this component)
• Icon only: IconButton
• Custom: ButtonLike

To create a more complex button than what the Button or IconButton components provide, use ButtonLike directly.

Examples

A button with a label, is typically used in scenarios such as a form, where the button’s label indicates what action will be performed when the button is clicked.

use ui::prelude::*;

Button::new("button_id", "Click me!")
    .on_click(|event, window, cx| {
        // Handle click event
    });

A toggleable button, is typically used in scenarios such as a toolbar, where the button’s state indicates whether a feature is enabled or not, or a trigger for a popover menu, where clicking the button toggles the visibility of the menu.

use ui::prelude::*;

Button::new("button_id", "Click me!")
    .start_icon(Icon::new(IconName::Check))
    .toggle_state(true)
    .on_click(|event, window, cx| {
        // Handle click event
    });

To change the style of the button when it is selected use the selected_style method.

use ui::prelude::*;
use ui::TintColor;

Button::new("button_id", "Click me!")
    .toggle_state(true)
    .selected_style(ButtonStyle::Tinted(TintColor::Accent))
    .on_click(|event, window, cx| {
        // Handle click event
    });

This will create a button with a blue tinted background when selected.

A full-width button, is typically used in scenarios such as the bottom of a modal or form, where it occupies the entire width of its container. The button’s content, including text and icons, is centered by default.

use ui::prelude::*;

let button = Button::new("button_id", "Click me!")
    .full_width()
    .on_click(|event, window, cx| {
        // Handle click event
    });

Implementations

impl Button

pub fn new(id: impl Into<ElementId>, label: impl Into<SharedString>) -> Self

Creates a new Button with a specified identifier and label.

This is the primary constructor for a Button component. It initializes the button with the provided identifier and label text, setting all other properties to their default values, which can be customized using the builder pattern methods provided by this struct.

pub fn color(self, label_color: impl Into<Option<Color>>) -> Self

Sets the color of the button’s label.

pub fn label_size(self, label_size: impl Into<Option<LabelSize>>) -> Self

Defines the size of the button’s label.

pub fn selected_label<L: Into<SharedString>>( self, label: impl Into<Option<L>>, ) -> Self

Sets the label used when the button is in a selected state.

pub fn selected_label_color(self, color: impl Into<Option<Color>>) -> Self

Sets the label color used when the button is in a selected state.

pub fn start_icon(self, icon: impl Into<Option<Icon>>) -> Self

Sets an icon to display at the start (left) of the button label.

The icon’s color will be overridden to Color::Disabled when the button is disabled.

pub fn end_icon(self, icon: impl Into<Option<Icon>>) -> Self

Sets an icon to display at the end (right) of the button label.

The icon’s color will be overridden to Color::Disabled when the button is disabled.

pub fn key_binding(self, key_binding: impl Into<Option<KeyBinding>>) -> Self

Display the keybinding that triggers the button action.

pub fn key_binding_position(self, position: KeybindingPosition) -> Self

Sets the position of the keybinding relative to the button label.

This method allows you to specify where the keybinding should be displayed in relation to the button’s label.

pub fn alpha(self, alpha: f32) -> Self

Sets the alpha property of the color of label.

pub fn truncate(self, truncate: bool) -> Self

Truncates overflowing labels with an ellipsis (…) if needed.

Buttons with static labels should never be truncated, ensure this is only used when the label is dynamic and may overflow.

pub fn loading(self, loading: bool) -> Self

Displays a rotating loading spinner in place of the start_icon.

When loading is true, any start_icon is ignored. and a rotating

pub fn primary(self) -> Self

Convenience for a Tailwind-style solid “primary” button: solid palette::primary(600) background with white text.

Equivalent to .style(ButtonStyle::Tinted(TintColor::Accent)).

pub fn danger(self) -> Self

Convenience for a Tailwind-style solid “danger” button: solid palette::danger(600) background with white text.

Equivalent to .style(ButtonStyle::Tinted(TintColor::Error)).

pub fn soft(self) -> Self

Convenience for a Tailwind-style “soft” button: faint palette::primary(50) background with palette::primary(700) text.

Implemented as an additive background override on top of the Tinted(Accent) style, so it does not require a new ButtonStyle variant.

pub fn variant(self, variant: ButtonVariant) -> Self

shadcn/ui variant alias (recommended vocabulary).

Maps to existing ButtonStyle / convenience builders without renaming legacy .primary() / .danger() / .soft() call sites. For link-style buttons use [ButtonLink] instead.

pub fn shadcn_size(self, size: ButtonSizeAlias) -> Self

shadcn/ui size alias. Icon-only sizing uses IconButton, not this API.

Trait Implementations

impl ButtonCommon for Button

fn style(self, style: ButtonStyle) -> Self

Sets the visual style of the button.

fn size(self, size: ButtonSize) -> Self

Sets the size of the button.

fn tooltip( self, tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static, ) -> Self

Sets a tooltip that appears on hover.

Examples

Add a tooltip to a button:

use ui::{Tooltip, prelude::*};

Button::new("tooltip_button", "Hover Me")
    .tooltip(Tooltip::text("This is a tooltip"));

fn id(&self) -> &ElementId

A unique element ID to identify the button.

fn tab_index(self, tab_index: impl Into<isize>) -> Self

fn layer(self, elevation: ElevationIndex) -> Self

fn track_focus(self, focus_handle: &FocusHandle) -> Self

impl Clickable for Button

fn on_click( self, handler: impl Fn(&ClickEvent, &mut Window, &mut App) + 'static, ) -> Self

Sets the click handler that will fire whenever the element is clicked.

fn cursor_style(self, cursor_style: CursorStyle) -> Self

Sets the cursor style when hovering over the element.

impl Component for Button

fn scope() -> ComponentScope

Returns the scope of the component.

fn sort_name() -> &'static str

Returns a name that the component should be sorted by.

fn description() -> Option<&'static str>

An optional description of the component.

fn preview(_window: &mut Window, _cx: &mut App) -> Option<AnyElement>

The component’s preview.

fn id() -> ComponentId

The component’s unique identifier.

fn status() -> ComponentStatus

The ready status of this component.

fn name() -> &'static str

The name of the component.

impl Disableable for Button

fn disabled(self, disabled: bool) -> Self

Disables the button, preventing interaction and changing its appearance.

When disabled, the button’s icon and label will use Color::Disabled.

Examples

Create a disabled button:

use ui::prelude::*;

Button::new("disabled_button", "Can't Click Me")
    .disabled(true);

impl Documented for Button

const DOCS: &'static str = "An element that creates a button with a label and optional icons.\n\nCommon buttons:\n- Label, Icon + Label: [`Button`] (this component)\n- Icon only: [`IconButton`]\n- Custom: [`ButtonLike`]\n\nTo create a more complex button than what the [`Button`] or [`IconButton`] components provide, use\n[`ButtonLike`] directly.\n\n# Examples\n\n**A button with a label**, is typically used in scenarios such as a form, where the button\'s label\nindicates what action will be performed when the button is clicked.\n\n```\nuse ui::prelude::*;\n\nButton::new(\"button_id\", \"Click me!\")\n.on_click(|event, window, cx| {\n// Handle click event\n});\n```\n\n**A toggleable button**, is typically used in scenarios such as a toolbar,\nwhere the button\'s state indicates whether a feature is enabled or not, or\na trigger for a popover menu, where clicking the button toggles the visibility of the menu.\n\n```\nuse ui::prelude::*;\n\nButton::new(\"button_id\", \"Click me!\")\n.start_icon(Icon::new(IconName::Check))\n.toggle_state(true)\n.on_click(|event, window, cx| {\n// Handle click event\n});\n```\n\nTo change the style of the button when it is selected use the [`selected_style`][Button::selected_style] method.\n\n```\nuse ui::prelude::*;\nuse ui::TintColor;\n\nButton::new(\"button_id\", \"Click me!\")\n.toggle_state(true)\n.selected_style(ButtonStyle::Tinted(TintColor::Accent))\n.on_click(|event, window, cx| {\n// Handle click event\n});\n```\nThis will create a button with a blue tinted background when selected.\n\n**A full-width button**, is typically used in scenarios such as the bottom of a modal or form, where it occupies the entire width of its container.\nThe button\'s content, including text and icons, is centered by default.\n\n```\nuse ui::prelude::*;\n\nlet button = Button::new(\"button_id\", \"Click me!\")\n.full_width()\n.on_click(|event, window, cx| {\n// Handle click event\n});\n```\n"

The static doc comments on this type.

impl FixedWidth for Button

fn width(self, width: impl Into<DefiniteLength>) -> Self

Sets a fixed width for the button.

Examples

Create a button with a fixed width of 100 pixels:

use ui::prelude::*;

Button::new("fixed_width_button", "Fixed Width")
    .width(px(100.0));

fn full_width(self) -> Self

Makes the button take up the full width of its container.

Examples

Create a button that takes up the full width of its container:

use ui::prelude::*;

Button::new("full_width_button", "Full Width")
    .full_width();

impl IntoElement for Button

type Element = Component<Button>

The specific type of element into which the implementing type is converted. Useful for converting other types into elements automatically, like Strings

fn into_element(self) -> Self::Element

Convert self into a type that implements Element.

fn into_any_element(self) -> AnyElement

Convert self into a dynamically-typed AnyElement.

impl RenderOnce for Button

fn render(self, _window: &mut Window, cx: &mut App) -> ButtonLike

Render this component into an element tree. Note that this method takes ownership of self, as compared to Render::render() method which takes a mutable reference.

impl SelectableButton for Button

fn selected_style(self, style: ButtonStyle) -> Self

Sets the style for the button in a selected state.

Examples

Customize the selected appearance of a button:

use ui::prelude::*;
use ui::TintColor;

Button::new("styled_button", "Styled Button")
    .toggle_state(true)
    .selected_style(ButtonStyle::Tinted(TintColor::Accent));

impl Toggleable for Button

fn toggle_state(self, selected: bool) -> Self

Sets the selected state of the button.

Examples

Create a toggleable button that changes appearance when selected:

use ui::prelude::*;
use ui::TintColor;

let selected = true;

Button::new("toggle_button", "Toggle Me")
    .start_icon(Icon::new(IconName::Check))
    .toggle_state(selected)
    .selected_style(ButtonStyle::Tinted(TintColor::Accent))
    .on_click(|event, window, cx| {
        // Toggle the selected state
    });