Button Stateful
The Avonni Stateful Button is a toggleable button that switches between an off and on state with a single click. Use it for actions that have two states — follow/following, like/liked, subscribe/subscribed — where the button should visibly reflect whether it's currently active.
Overview
Unlike a standard button that simply fires an action, the Stateful Button remembers its state and changes its appearance to match. It supports three distinct looks: an off label and icon for the inactive state, an on label and icon for the active state, and an optional on-hover label and icon shown when an already-active button is hovered or focused (for example, switching a "Following" button to "Unfollow" on hover).
You can set the button's starting state, choose from several styling variants, disable it, and wire up an action to run each time it's clicked.
Configuration
To configure the Stateful Button, select it on the canvas. The Edit Stateful Button panel opens on the right. The sections below mirror the configuration panel.
Properties
Off State
These settings control how the button appears when it is off (inactive):
Label When Off — the text displayed while the button is in the off state.
Icon Name When Off — the Lightning Design System icon displayed while the button is in the off state (for example,
utility:add).
On State
These settings control how the button appears when it is on (active):
Label When On — the text displayed while the button is in the on state.
Icon Name When On — the Lightning Design System icon displayed while the button is in the on state (for example,
utility:check).
On-Hover State
These settings let you change the button's look when an active button is hovered or focused — useful for prompting the user to undo the action:
Label When Hover — the text displayed when the state is on and the button is hovered or focused.
Icon Name When Hover — the Lightning Design System icon displayed when the state is on and the button is hovered or focused.
Selected
Selected sets the button's initial state. When enabled, the button starts in the on state; when disabled, it starts in the off state.
Variant
The Variant sets the color and visual style of the button so you can align it with its purpose. Available options: Neutral (default), Brand, Destructive, Inverse, Success, and Text.
Disabled
When Disabled is enabled, the button is greyed out and cannot be clicked. Use it to prevent toggling until certain conditions are met.
Set Component Visibility
All components support conditional visibility — see Component Visibility.
Styling
The Style tab gives you fine-grained control over the Stateful Button's appearance. Configure it from the Style tab of the Edit Stateful Button panel. The variant-specific sections below adapt to the Variant chosen in the Properties tab.
Controls the outer spacing around the button.
Top / Right / Bottom / Left: Adjust the space on each side.
Controls the inner spacing inside the button.
Top / Right / Bottom / Left: Adjust the space on each side.
Sets the horizontal alignment of the button within its container.
Horizontal Alignment: Choose how the button is justified.
Adjusts the internal block and inline spacing of the button (set per variant: Brand, Destructive, Inverse, Neutral, Success, Text).
Block Start / Block End: Set the vertical spacing.
Inline Start / Inline End: Set the horizontal spacing.
Customizes the label text (set per variant: Brand, Destructive, Inverse, Neutral, Success, Text).
Line Height: Set the line height of the label.
Color / Color Active / Color Hover: Set the text color in each state.
Sets the button background (set per variant: Brand, Destructive, Inverse, Neutral, Success, Text).
Color / Color Active / Color Hover: Set the background color in each state.
Color Selected / Color Selected Active / Color Selected Hover: Set the background color for the on (selected) state — available for the Neutral and Text variants.
Customizes the border (set per variant: Brand, Destructive, Inverse, Neutral, Success, Text).
Size: Adjust the border thickness.
Radius: Control the roundness of the corners.
Color / Color Active / Color Hover: Set the border color in each state.
Color Selected / Color Selected Hover: Set the border color for the on (selected) state — available for the Neutral and Text variants.
Interactions
Interactions define what happens when users interact with the Stateful Button. Configure them from the Interactions tab of the Edit Stateful Button panel.
Click
Fires each time the user clicks the button. The button automatically toggles the Selected output between on and off — use this interaction to run a flow action, navigate, or update other components in response to the state change.
Troubleshooting Common Issues
Button Doesn't Change State: Confirm that both Label When Off and Label When On (or their icon equivalents) are set — without distinct off/on values, the toggle has nothing visible to switch between.
Starts in the Wrong State: Check the Selected setting. Enable it to have the button start on; disable it to start off.
No Hover Change: The on-hover look only applies while the button is in the on state. Set Label When Hover and/or Icon Name When Hover, and verify the button is currently on.
Icons Not Showing: Verify each icon uses a valid Lightning Design System name (for example,
utility:check); a misspelled or unsupported name renders nothing.Button Can't Be Clicked: Make sure Disabled isn't enabled, and check the component's visibility conditions.
Click Action Not Firing: Confirm an action is configured under On Click and test any bindings with static values first.
Last updated
Was this helpful?