> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/button-stateful.md). # 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. #### On Click Use the **On Click** interaction to define what happens each time the button is clicked — for example, navigating, updating a variable, or triggering another action. ### Set Component Visibility All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md). ## 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. {% tabs %} {% tab title="Margin" %} Controls the *outer* spacing around the button. * **Top / Right / Bottom / Left:** Adjust the space on each side. {% endtab %} {% tab title="Padding" %} Controls the *inner* spacing inside the button. * **Top / Right / Bottom / Left:** Adjust the space on each side. {% endtab %} {% tab title="Horizontal Alignment" %} Sets the horizontal alignment of the button within its container. * **Horizontal Alignment:** Choose how the button is justified. {% endtab %} {% tab title="Spacing" %} 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. {% endtab %} {% tab title="Text" %} 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. {% endtab %} {% tab title="Background" %} 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. {% endtab %} {% tab title="Border" %} 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. {% endtab %} {% endtabs %} ## Interactions [Interactions](/dynamic-components/component-builder/interactions.md) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avonnicomponents.com/dynamic-components/components/button-stateful.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.