Struct Button 

pub struct Button<'a> { /* private fields */ }

Clickable themed button, built on egui Atoms.

Reads ButtonVisuals from the installed Theme unless you pass .visuals(...). Use Button::bg_color for a one-off idle fill (semantic actions). Chromatic fills should use theme.colors.bg as the text color so glyphs stay readable.

if ui.add(Button::new("Save")).clicked() {
    // …
}

Implementations

impl<'a> Button<'a>

pub fn new(atoms: impl IntoAtoms<'a>) -> Self

Create a button from atoms (text, images, or a mix).

pub fn selectable(selected: bool, atoms: impl IntoAtoms<'a>) -> Self

Show a selectable button.

Equivalent to:

let selected = true;
ui.add(Button::new("toggle me").selected(selected).frame_when_inactive(!selected).frame(true));

See also:

• Ui::selectable_value
• Ui::selectable_label

pub fn image(image: impl Into<Image<'a>>) -> Self

Creates a button with an image. The size of the image as displayed is defined by the provided size.

Note: In contrast to Button::new, this limits the image size to the default font height (using egui::AtomExt::atom_max_height_font_size).

pub fn image_and_text( image: impl Into<Image<'a>>, text: impl Into<WidgetText>, ) -> Self

Creates a button with an image to the left of the text.

Note: In contrast to Button::new, this limits the image size to the default font height (using egui::AtomExt::atom_max_height_font_size).

pub fn opt_image_and_text( image: Option<Image<'a>>, text: Option<WidgetText>, ) -> Self

Create a button with an optional image and optional text.

Note: In contrast to Button::new, this limits the image size to the default font height (using egui::AtomExt::atom_max_height_font_size).

pub fn wrap_mode(self, wrap_mode: TextWrapMode) -> Self

Set the wrap mode for the text.

By default, egui::Ui::wrap_mode will be used, which can be overridden with egui::Style::wrap_mode.

Note that any \n in the text will always produce a new line.

pub fn wrap(self) -> Self

Set Self::wrap_mode to TextWrapMode::Wrap.

pub fn truncate(self) -> Self

Set Self::wrap_mode to TextWrapMode::Truncate.

pub fn small(self) -> Self

Make this a small button, suitable for embedding into text.

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

If false, the button will not have a frame when inactive.

Default: true.

Note: When ui.visuals().button_frame is false, this setting has no effect.

pub fn sense(self, sense: Sense) -> Self

By default, buttons senses clicks. Change this to a drag-button with Sense::drag().

pub fn min_size(self, min_size: Vec2) -> Self

Set the minimum size of the button.

pub fn label_align(self, align: Align) -> Self

Align the button’s atoms within its Self::min_size rect.

Defaults to Align::Min, which leaves the atoms where the surrounding Ui layout puts them — the rendering from before this builder existed.

The implementation sets the horizontal component of the atom layout’s AtomLayout::align2: it moves the measured block of atoms inside the allocated rect. It does not use the layout’s main-axis justification, which would stretch the gap between atoms instead of moving the block.

A trailing grow atom — added by Self::right_text or Self::shortcut_text — makes the atom block fill the rect, so there is no leftover space for this alignment to move and the trailing text stays pinned to the right edge under every alignment.

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

If true, the tint of the image is multiplied by the widget text color.

This makes sense for images that are white, that should have the same color as the text color. This will also make the icon color depend on hover state.

Default: false.

pub fn shortcut_text(self, shortcut_text: impl Into<Atom<'a>>) -> Self

Show some text on the right side of the button, in weak color.

Designed for menu buttons, for setting a keyboard shortcut text (e.g. Ctrl+S).

The text can be created with egui::Context::format_shortcut.

See also Self::right_text.

pub fn right_text(self, right_text: impl Into<Atom<'a>>) -> Self

Show some text on the right side of the button.

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

If true, mark this button as “selected”.

pub fn visuals(self, visuals: ButtonVisuals) -> Self

Set the visuals of the button

pub fn bg_color(self, color: Color32) -> Self

Set the background color of the button

pub fn badge(self, badge: Badge) -> Self

Attach a notification Badge to a corner of this button.

The badge is painted on top of the button and does not change its size or layout. Use it to signal unseen content behind the button — e.g. a red circle with the number of notifications.

ui.add(
   Button::new("Notifications").badge(
      Badge::new("3")
         .color(Color32::RED)
         .corner(BadgeCorner::TopRight),
   ),
);

pub fn hold(self, seconds: f32) -> Self

Arm the button as hold-to-confirm.

clicked then reports true only once the pointer has been held down on the button for seconds — never for a plain click. A non-positive seconds leaves the button as an ordinary click button.

The widget tracks the press itself: it latches egui’s hit test at press time and then follows the raw pointer, so the hold works for durations longer than egui’s max_click_duration (0.8 s by default), past the point where egui stops treating the press as a potential click. Releasing the button, or dragging the pointer further than max_click_dist away from it, cancels the hold.

Note for touch screens: egui may additionally report a long touch as a secondary-click (context menu) once the press passes max_click_duration; this widget does not consume that.

While the hold progresses the frame’s fill is replaced by a left-to-right sweep that grows as the hold completes; when it fills, the button fires once and plays its HoldSettings::burst. Pressing Enter or Space on a focused button confirms immediately, like egui’s keyboard activation for buttons.

This shortcut only sets HoldSettings::seconds; every other field keeps its current value, so shortcuts compose in call order.

pub fn hold_fill(self, color: Color32) -> Self

Set a solid hold-sweep colour, and the default tint of a HoldBurst::Glow burst.

This sets HoldSettings::fill_from and clears HoldSettings::fill_to, so the sweep stays one colour; use Self::hold_settings for a colour that shifts as the hold fills.

Defaults to the installed theme’s colors.accent. This shortcut does not arm the hold on its own — call Self::hold or Self::hold_settings too.

pub fn hold_burst(self, burst: HoldBurst) -> Self

Set the completion burst played when the hold fires.

This sets HoldSettings::burst. Default: HoldBurst::Glow. This shortcut does not arm the hold on its own — call Self::hold or Self::hold_settings too.

pub fn hold_settings(self, settings: &HoldSettings) -> Self

Replace the whole hold configuration with settings.

Copies every field, including HoldSettings::seconds; a value of 0.0 or less leaves the button as an ordinary click button. The most recent of this call and the per-field shortcuts wins for the fields it sets.

pub fn atom_ui(self, ui: &mut Ui) -> AtomLayoutResponse

Show the button and return a AtomLayoutResponse for painting custom contents.

Trait Implementations

impl Widget for Button<'_>

fn ui(self, ui: &mut Ui) -> Response

Allocate space, interact, paint, and return a Response.

fn boxed<'a>(self) -> Box<dyn FnOnce(&mut Ui) -> Response + 'a>

where Self: Sized + 'a,

Box this widget for dynamic dispatch.