Push Button

Class: FxPushButton · Tag: <fx-push-button> · Mixins: Animatable

The <fx-push-button> component is a high-reliability hardware-style tactile push button. It supports customizable geometry profiles, active state latching or momentary triggers, and slotted icon capabilities.

Installation

import '@salsafx/ui';

Interactive preview of the main variants:

No Icon

With Icon

Rounded Rect

Rect

Basic Usage

1. Button Without Icon (Start)

A standard momentary round push button without any icon, using an external plate label:

State: Inactive

<fx-push-button
    label="Start"
    background-color="#06b6d4"
    type="momentary"
    shape="round"
></fx-push-button>

2. Button With Icon (Power)

A momentary round push button with an external plate label and a FontAwesome icon via the icon attribute:

State: Inactive

<fx-push-button
    label="Power"
    background-color="#3b82f6"
    type="momentary"
    shape="round"
    icon="fa-solid fa-power-off"
></fx-push-button>

3. Button With Embedded Text (Stop)

A latching rectangular push button with rounded corners (same radius as FxSwitch buttons) and an embedded text label:

State: Inactive

<fx-push-button
    label="Stop"
    label-position="inside"
    background-color="#ef4444"
    type="latching"
    shape="roundedRect"
></fx-push-button>

4. Rectangular Button (Industrial Reset)

A sharper rectangular profile with a slight corner radius:

State: Inactive

<fx-push-button
    label="Reset"
    label-position="inside"
    background-color="#10b981"
    type="momentary"
    shape="rect"
    text-rendering-mode="shaded"
></fx-push-button>

5. Icon and Text Together (Shaded)

Embedded label with an icon attribute — both rendered in shaded mode:

text + icon · both shaded

<fx-push-button
    label="Reset"
    label-position="inside"
    background-color="#6366f1"
    shape="roundedRect"
    text-rendering-mode="shaded"
    icon-rendering-mode="shaded"
    icon="fa-solid fa-rotate-right"
></fx-push-button>

Shapes

All geometry profiles side by side: round (circle), pill (stadium — semicircle caps with a straight middle), roundedRect (same radius as FxSwitch buttons), and rect (near-square corners).

round

pill

roundedRect

rect

<fx-push-button
    label="Start"
    shape="round"
    background-color="#06b6d4"
>
    <i slot="icon" class="fa-solid fa-play"></i>
</fx-push-button>

<fx-push-button
    label="Evacuate"
    label-position="inside"
    shape="pill"
    background-color="#fdba74"
    type="latching"
></fx-push-button>

<fx-push-button
    label="Stop"
    label-position="inside"
    shape="roundedRect"
    background-color="#ef4444"
    type="latching"
></fx-push-button>

<fx-push-button
    label="Reset"
    label-position="inside"
    shape="rect"
    background-color="#10b981"
    text-rendering-mode="shaded"
></fx-push-button>

API Reference

Properties & Attributes

Property	Attribute	Type	Default	Description
`label`	`label`	`String`	`""`	Button text label.
`labelPosition`	`label-position`	`String`	`"plate"`	Label placement (“plate”, “inside”, or “none”).
`type`	`type`	`String`	`"momentary"`	Button behavior type (“momentary” or “latching”).
`isActive`	`is-active`	`Boolean`	`false`	Whether the button is currently pressed or latched.
`disabled`	`disabled`	`Boolean`	`false`	Disables the control and prevents user interaction.
`backgroundColor`	`background-color`	`String`	`"#6366f1"`	Button face background color.
`foregroundColor`	`foreground-color`	`String`	`"#ffffff"`	Text and icon color override.
`icon`	`icon`	`String`	`""`	Icon-font class list (e.g. `"fa-solid fa-power-off"`) or a path ending in `.svg`.
`textRenderingMode`	`text-rendering-mode`	`String`	`"foregroundColor"`	Coloring mode for the text label (“foregroundColor” or “shaded”).
`iconRenderingMode`	`icon-rendering-mode`	`String`	`"shaded"`	Coloring mode for the icon (“shaded” or “foregroundColor”).
`shape`	`shape`	`String`	`"round"`	Button shape (“round”, “pill”, “roundedRect”, or “rect”).
`isAnimated`	`is-animated`	`Boolean`	`true`	Enables fluid, tactile animations and transitions.

Slots

Name	Description
`icon`	Named slot for inserting custom FontAwesome icons inside the button face. Prefer the `icon` attribute for standard FA classes; use the slot for custom markup.
—	Default slot for custom content when `labelPosition` is `"inside"` or `"none"`.

Events

Name	Detail	Description
`change`	`{ active: Boolean, isActive: Boolean, type: String }`	Dispatched when the active state undergoes modification.
`press`	`{ active: Boolean, isActive: Boolean }` or empty	Dispatched on button depression.
`release`	empty	Dispatched on button release (momentary only).

CSS Custom Properties

Property	Default	Description
`--fx-font-family`	`sans-serif`	Component typography font family.
`--fx-push-button-font-size`	`0.875rem`	Label text size.
`--fx-push-button-background-color`	`#6366f1`	Button cap face fill color.
`--fx-push-button-foreground-color`	`#ffffff`	Color for text/icon when rendering mode is `"foregroundColor"`.

Object Hierarchy

classDiagram
    direction TB
    class FxElement
    class FxPushButton

    FxElement <|-- FxPushButton : Animatable