Toggles

<cv-toggle>

Toggles let you show or hide sections of a page based on a category (for example: mac, linux, windows). They are ideal for platform-specific content, progressive disclosure, or audience-targeted sections.

<cv-toggle toggle-id="mac">

**macOS**: macOS-specific install steps...
* Macbook Pro
* Macbook Neo
</cv-toggle>

<cv-toggle toggle-id="windows">

**Windows**: Windows-specific install steps...
* Windows Vista
* Windows XP
* Windows 11
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

When the active toggle state includes mac, only the <cv-toggle toggle-id="mac"> element will be visible. The component reactively updates based on the global toggle state.

Basic Syntax

<cv-toggle toggle-id="mac">
  Content only visible when the "mac" toggle is active.
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The toggle-id links the element to a configured toggle category. When show, content is visible. When hide, it is hidden. When peek, a collapsed preview is shown.

Toggle Peek Mode

You can set a toggle to "peek" mode, where it shows a preview of the content. Use show-peek-border to add a border to the peek view to make it stand out. Additionally, use show-label to add a label to the toggle, so users know what it is.

• Short toggle content: If the content height is less than the peek height (70px), the full content is shown without the "expand" button or fade effect.

<cv-toggle toggle-id="localToggle" show-peek-border show-label><br>

**Local toggle content**:
* Item 1
* Item 2
* Item 3
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Multi-ID Toggles

You can apply multiple toggles to a single element by separating categories with spaces. This allows content to appear as long as one toggle category is active.

• Precedence Behaviour: When multiple IDs are used, it uses the most visible state out of all the IDs.

<cv-toggle toggle-id="mac linux">
  This section appears for both macOS and Linux users.
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Placeholder-Driven Toggles

A toggle can also be shown or hidden based on whether a placeholder has been set by the reader, using placeholder-id instead of toggle-id:

<cv-toggle placeholder-id="username">
  Welcome, \[[username]]! These are your personalised instructions.
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The block is hidden when username has no value, and visible when it does. See Placeholder-Driven Toggles for full details.

Attributes of <cv-toggle>

Toggle Control

<cv-toggle-control>

You can place a toggle control directly on the page so readers can switch a toggle's visibility state (Hide · Peek · Show) without opening the Settings modal. By default it renders as a card, matching the look of the settings panel, with the toggle's label shown on the left and the segmented control on the right.

• You can place the control anywhere, above the toggle, in a sidebar, or grouped together for multiple toggles.
• To hide the label and render only the segmented control inline, add the inline attribute.
• Note: cv-toggle-control renders nothing for siteManaged toggles, since those states are controlled by the site rather than the reader.

<cv-toggle-control toggle-id="localToggle"></cv-toggle-control> <br>

Control the toggles for the id `localToggle` here: <cv-toggle-control toggle-id="localToggle" inline></cv-toggle-control>

<cv-toggle toggle-id="localToggle"> 

**Local Toggle**: Local toggle content
* Item 1
* Item 2
* Item 3
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Attributes of <cv-toggle-control>

Configuration

To make toggles discoverable by the settings, you must define them in your custardui.config.json.

{
  "config": {
    "toggles": [
      {
        "toggleId": "mac",
        "label": "MacOS",
        "description": "Show content for macOS users",
        "default": "show"
      },
      {
        "toggleId": "linux",
        "label": "Linux",
        "description": "Show content for Linux users",
        "default": "peek"
      },
      { "toggleId": "windows", "label": "Windows", "default": "hide" },
      {
        "toggleId": "localToggle",
        "label": "Local Toggle",
        "description": "Show content for local users",
        "isLocal": true
      }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Configuration Fields

Visibility is resolved in this order, stopping at the first match:

This means a shareable URL can override specific toggles without resetting the recipient's other preferences.

Global vs. Local Toggles

By default, all toggles defined in your configuration are global—they will appear in the settings on every page of your site.

You can mark a toggle as local to make it appear in the settings only on pages where that specific toggle is actually used. This is useful for keeping the settings clean and only showing relevant options to the user.

To mark a toggle as local, add "isLocal": true to its configuration.

Example:

If you have a mac toggle that is only used on a few pages, setting it as local ensures the "MacOS" option only appears in the settings on those pages.

{
  "config": {
    "toggles": [
      { "toggleId": "mac", "label": "MacOS", "isLocal": true },
      { "toggleId": "linux", "label": "Linux" },
      { "toggleId": "windows", "label": "Windows" }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Keeping Local Toggles in Settings

If you have a specific use case where you may want all local toggles to be available in the settings on a certain page, (e.g. a global settings page), you can add hidden cv-toggle elements to register the local toggles on that page. That way, the plugin will pick them up and add them to the settings dialog for that page without introducing extra spacing in your layout.

• E.g. <cv-toggle toggle-id="localToggle" hidden></cv-toggle>

Site-Managed Toggles

If an adaptation needs to lock a toggle — preventing users from changing it via the settings modal, a shared URL, or their saved preferences — mark it with siteManaged: true:

{
  "config": {
    "toggles": [
      { "toggleId": "java",   "label": "Java",   "default": "show", "siteManaged": true },
      { "toggleId": "python", "label": "Python",  "default": "hide", "siteManaged": true }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The adaptation can then override the default state via preset.toggles:

{
  "id": "nus",
  "preset": {
    "toggles": { "java": "show", "python": "hide" }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

A site-managed toggle:

• Does not appear in the settings modal.
• Is not included in generated shareable URLs.
• Ignores any visibility state stored in localStorage or supplied via URL parameters.

See Site-Managed Components in the Adaptation Configurations guide for the full picture.

Shareable URL

Toggle visibility states can be encoded directly in a URL so that a recipient sees the exact combination of shown, peeked, and hidden content that you intend.

Each toggle ID is encoded with encodeURIComponent and joined with commas, so IDs containing special characters are handled safely. Only the toggle IDs explicitly listed in the URL are affected — all others fall back to the visitor's saved preferences or the configured defaults.

Example:

https://yoursite.com/install.html?t-show=mac,linux&t-hide=windows

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Constructing the URL in JavaScript:

const show  = ['mac', 'linux'];
const hide  = ['windows'];
const url   = `https://yoursite.com/install.html`
            + `?t-show=${show.map(encodeURIComponent).join(',')}`
            + `&t-hide=${hide.map(encodeURIComponent).join(',')}`;

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Troubleshooting

• Toggles not appearing in settings? Check that your config.toggles array is correctly formatted with toggleId and label for each toggle.
• No effect when toggling? Ensure the element uses <cv-toggle toggle-id="..."> and the category matches a configured toggle ID.
• Settings icon not loading? Verify the script is included and custardui.config.json is accessible.