# Toggle

## Overview

The Toggle component renders a slider that users can flip between two states — on (checked) or off (unchecked). The current state is exposed as a Boolean value you can bind to a Record field, a Resource Variable, or a Component Visibility rule.

Use it for user preferences ("Receive email notifications"), feature toggles ("Show advanced fields"), or anywhere you'd otherwise use a checkbox but want a more deliberate, switch-like interaction.

***

## Quick Start: Toggle Component Visibility on a Record Page

This walkthrough adds a toggle that shows or hides a Record Detail panel based on the user's choice.

<figure><img src="/files/0T5tQOAvLCxHBWlfhcUv" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### **Add the Toggle component to the Canvas**

* From the **Component Library** (left sidebar), drag the **Toggle** component onto the Canvas.
* Set **Label** to `Show Details`.
* Set **Variant** to `Label Inline` so the label sits on the left and the toggle on the right.
  {% endstep %}

{% step %}

#### **Bind Checked to a Resource Variable**

* In the Properties Panel, click into the **Checked** field.
* Switch to advanced expression mode and create a new **Boolean** Resource Variable called `ShowDetails` with default `false`.
* Bind **Checked** to `{!ShowDetails}`.

*Why: Binding to a Variable lets the toggle's state be referenced anywhere else on the page — including visibility rules on other components.*
{% endstep %}

{% step %}

#### **Add a Record Detail (or any component) to control**

* Drag a **Record Detail**, **Card**, or any container next to the Toggle.
* In that component's properties, find the **Component Visibility** rule.
* Add a rule: visible when `{!ShowDetails}` equals `true`.

*Why: This wires the Toggle's state directly to the component's visibility — flipping the toggle instantly hides or shows the panel, with no Interaction needed.*

<figure><img src="/files/M07Ma5APvYQpM0WfOwIy" alt="" width="375"><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### **Save and Activate**

* Click **Save** in the top right.
* Click **Activate** and [add the component to a Lightning Page](/dynamic-components/core-concepts/publishing-your-dynamic-components.md) using the Lightning App Builder.
  {% endstep %}
  {% endstepper %}

***

## Configuration

The Toggle component has three configuration areas: the **General** properties (label, value, layout), the **Behavior** properties (required, read-only, disabled), and the **Active/Inactive** messages displayed alongside the switch.

### General Settings

These appear in the Properties Panel after selecting the Toggle component.

| Setting              | Description                                                                                             | Options / Default                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **Label**            | Text shown alongside the toggle. Should clearly state what the toggle controls.                         | Free text                                                             |
| **Checked**          | The current state of the toggle. Bind to a Boolean Resource Variable, Record field, or formula.         | `true` (on) / `false` (off, default)                                  |
| **Field Level Help** | Help text shown next to the label as a tooltip on the help icon.                                        | Free text                                                             |
| **Variant**          | Layout style — controls where the label appears relative to the toggle.                                 | `Standard` (default), `Label Hidden`, `Label Inline`, `Label Stacked` |
| **Size**             | Visual size of the switch.                                                                              | `X-Small`, `Small`, `Medium` (default), `Large`                       |
| **Hide Mark**        | Hides the checkmark icon inside the toggle when it's on. The sliding animation alone signals the state. | On / Off (default: off)                                               |

**Variant Reference**

| Variant           | Layout                                                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard**      | Label appears above the toggle. Default for most form-style layouts.                                                                    |
| **Label Inline**  | Label appears to the left, toggle on the right. Use this when fitting a toggle into a row alongside other inline content.               |
| **Label Stacked** | Label appears above the toggle, explicitly stacked. Visually similar to Standard but more compact.                                      |
| **Label Hidden**  | Label is hidden visually but remains available to screen readers. Only use when the toggle's purpose is clear from surrounding context. |

#### Behavior Settings

| Setting                        | Description                                                                                                          | Options / Default                              |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Required**                   | Marks the toggle as required for form submission. Pairs with **Message When Value Missing**.                         | On / Off (default: off)                        |
| **Message When Value Missing** | Error message shown if **Required** is on and the toggle is left off at submission.                                  | Free text — only shown when **Required** is on |
| **Disabled**                   | Greys out the toggle and prevents all interaction. The current state still displays.                                 | On / Off (default: off)                        |
| **Read Only** *(advanced)*     | The toggle's state displays but users can't change it. Visually distinct from Disabled — preserves the active style. | On / Off (default: off)                        |

{% hint style="info" %}

#### **Disabled vs Read Only**

Use **Disabled** when the toggle is temporarily unavailable (waiting on another field, user lacks permission). Use **Read Only** when the value is final and shouldn't be edited (locked record, audit-only display)
{% endhint %}

#### Active / Inactive Messages *(advanced)*

By default, the toggle shows "Active" when on and "Inactive" when off, next to the switch. Override these in the advanced section of the Properties Panel.

| Setting                     | Description                        | Default    |
| --------------------------- | ---------------------------------- | ---------- |
| **Message Toggle Active**   | Text shown when the toggle is on.  | `Active`   |
| **Message Toggle Inactive** | Text shown when the toggle is off. | `Inactive` |

Common overrides: `On` / `Off`, `Yes` / `No`, `Enabled` / `Disabled`, `Show` / `Hide`.

***

## Interactions

The Toggle exposes a single trigger that fires whenever the user flips it.

| Trigger    | Fires When                                                                            | Common Actions                                                    |
| ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Change** | The user switches the toggle on or off. Does not fire for programmatic value changes. | Update Record, Execute Flow, Update Variable, Refresh Record Page |

### Output Variables

When the Change trigger fires, the following variable is available to use in any action:

| Output Variable | Type    | Contains                                                                              |
| --------------- | ------- | ------------------------------------------------------------------------------------- |
| **Checked**     | Boolean | The new state of the toggle (`true` if it was just turned on, `false` if turned off). |

### Common Action: Save the Toggle State to a Record Field

Use this when the toggle controls a real Salesforce field — for example, a custom checkbox `Send_Weekly_Digest__c` on Contact.

1. Bind **Checked** to `{!$Record.Send_Weekly_Digest__c}` so the initial state matches the record.
2. Open the **Interactions** tab.
3. On the **Change** trigger, add an **Update Record** action.
4. Map fields:
   * **Object:** `Contact`
   * **Record ID:** `{!$Record.Id}`
   * **Send\_Weekly\_Digest\_\_c:** `{!Checked}`
5. Optionally chain a **Show Toast** action so the user gets feedback.

### Common Action: Run a Flow Only When Turned On

If you want a Flow to fire only when the toggle is switched on (not off), use a condition on the action:

1. On the **Change** trigger, add **Execute Flow**.
2. In the action's condition, set: `{!Checked}` equals `true`.
3. Configure the Flow's input variables with whatever record context it needs.

***

## Examples

### Email Notification Preference

A toggle on a Contact record that turns the weekly newsletter on or off.

{% stepper %}
{% step %}

#### **Configure the Toggle**

* **Label:** `Subscribe to Weekly Newsletter`
* **Variant:** `Label Inline`
* **Size:** `Medium`
* **Checked:** `{!$Record.Newsletter_Subscribed__c}`
* **Message Toggle Active:** `Subscribed`
* **Message Toggle Inactive:** `Unsubscribed`&#x20;
  {% endstep %}

{% step %}

#### **Wire the Change interaction to update the record**

* On the **Change** trigger, add **Update Record**:
  * **Object:** `Contact`
  * **Record ID:** `{!$Record.Id}`
  * **Newsletter\_Subscribed\_\_c:** `{!Checked}`
* Add a **Show Toast** action: "Subscription preference updated."&#x20;
  {% endstep %}
  {% endstepper %}

### Show Advanced Fields on a Form

A page-level toggle that reveals a section of advanced fields only when the user wants to see them.

{% stepper %}
{% step %}

#### **Add the Toggle and a Resource Variable**

* Drag in the Toggle, **Label:** `Show advanced options`.
* Create a Boolean Resource Variable `ShowAdvanced` (default `false`).
* Bind **Checked** to `{!ShowAdvanced}`.
  {% endstep %}

{% step %}

#### **Wrap the advanced fields in a Container**

* Wrap the advanced fields in a **Container** (or **Columns**) component.
* On the Container, set **Component Visibility** to: visible when `{!ShowAdvanced}` equals `true`.
  {% endstep %}
  {% endstepper %}

***

## Troubleshooting

| Problem                                                       | Cause                                                                                                                                                         | Fix                                                                                                                                                      |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Flipping the toggle doesn't update the bound record field     | No Interaction is configured on the **Change** trigger, or the Update Record action is missing the field mapping.                                             | Add an **Update Record** action on the Change trigger and map the toggle's **Checked** output to the target field.                                       |
| Toggle initial state doesn't match the record                 | **Checked** isn't bound to the record's field — it's set to a static value or left empty.                                                                     | Bind **Checked** to `{!$Record.YourFieldName__c}` so the toggle reads the current value when the page loads.                                             |
| Toggle visually flips but the **Change** trigger doesn't fire | The toggle is **Disabled** — disabled toggles don't dispatch the Change event.                                                                                | Turn off **Disabled**, or use **Read Only** instead if you only want to prevent edits while still showing the state.                                     |
| Required setting doesn't block form submission                | Required only blocks submission when the toggle is part of a form context. On a Record Page without a wrapping form, the Required check has no effect.        | Use a Validation Rule on the underlying Salesforce field instead, or wrap the toggle in a form-style container with submission logic.                    |
| Component Visibility rule based on the toggle doesn't work    | The toggle's **Checked** is bound to a Record field, not a Resource Variable. Visibility rules read from variables, not from in-memory toggle state.          | Bind **Checked** to a Resource Variable, then use that Variable in the visibility rule. Optionally, also write back to the record on the Change trigger. |
| "Active" / "Inactive" labels appear instead of custom text    | **Message Toggle Active** / **Message Toggle Inactive** are in the advanced section of the Properties Panel and were left blank.                              | Open the advanced section and set the messages to your preferred text (for example, `On` / `Off`).                                                       |
| Toggle is too small to tap reliably on phones                 | **Size** is set to `X-Small` or `Small`.                                                                                                                      | Use **Medium** (default) or **Large** for any toggle on a touch-first page.                                                                              |
| Hide Mark setting doesn't seem to do anything                 | The mark is only visible when the toggle is on — Hide Mark removes the checkmark from the on-state. If you're testing in the off-state, no change is visible. | Flip the toggle on to verify the mark is hidden.                                                                                                         |
| The toggle doesn't appear at all on the deployed page         | A Component Visibility rule is hiding it, or the parent container's visibility is false.                                                                      | Inspect the visibility rule on the Toggle and on every parent container up the tree.                                                                     |

***

### Key Considerations

* The Toggle is a form input — its state is only meaningful when bound to something. Always bind **Checked** to a Resource Variable or a Record field, not a static value.
* Use **Resource Variables** when the toggle controls UI behavior (visibility, conditional logic on the page). Use **Record fields** when the toggle persists a setting on the Salesforce record.
* Pair every Required toggle with a clear **Message When Value Missing** — generic validation messages frustrate users.
* For touch-first pages, stick with **Medium** or **Large** sizes. **X-Small** is hard to hit accurately on phones.
* Use **Label Inline** for settings rows ("Active", "Notify me", "Auto-renew") and **Standard** for form-style layouts where labels stack above inputs.
* Disabled toggles do not fire the Change trigger. If you need to react to programmatic state changes, use a separate Resource Variable observer rather than the toggle's interaction.
* For yes/no fields where the visual switch metaphor doesn't fit (filtering, multi-option logic), use a Checkbox or Choice Set instead — the Toggle should signal a binary on/off state


---

# Agent Instructions: 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:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/toggle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.