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...
</cv-toggle>

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

**Linux**: Linux-specific install steps...
</cv-toggle>

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

**Windows**: Windows-specific install steps...
</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.

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.

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Toggles with 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. We recommend show-label to add a label to the toggle, so users know what it is.

<cv-toggle toggle-id="toggle1" show-peek-border show-label>
  <p>This content is in peek mode!</p>
</cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Precedence Behaviour:

When multiple IDs are used, the effective visibility is determined by the most "positive" state among all matching IDs. The order of precedence is:

1. Show (Highest)
2. Peek
3. Hide (Lowest)

Logic:

• If ANY of the IDs are set to Show, the content is completely Shown.
• If NONE show, but ANY are Peek, the content is shown in Peek mode.
• If ALL are Hide (or undefined), the content is Hidden.

This means that "Show" overrides "Peek", and "Peek" overrides "Hide". Explicit interest always overrides disinterest.

Attributes & Options of <cv-toggle>

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
    

    


    
    
    

Key Configuration Fields in custardui.config.json for Toggles

Visibility Resolution Order

Visibility is resolved by layering state in this order:

1. URL State (Sparse Overrides): If a toggle is explicitly mentioned in the URL (e.g., ?t-show=A), it wins.
2. Persisted State: If not in the URL, the state stored in the browser's local storage is used.
3. Default Configuration: If neither of the above are present, the default value from custardui.config.json is used.

This means you can share a link that overrides specific toggles (like hiding a normally-visible section) without completely resetting the recipient's other local 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": "localToggle", "label": "Local Toggle", "isLocal": true },
      { "toggleId": "mac", "label": "MacOS", "isLocal": false },
      { "toggleId": "linux", "label": "Linux" },
      { "toggleId": "windows", "label": "Windows" }
    ]
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

And present on this page:

<cv-toggle toggle-id="localToggle"> Local Toggle content </cv-toggle>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Registering Local Toggles for Settings

You can ensure that specific local toggles are always available in the settings, even if they are not initially visible on the page. This is useful for toggles that are loaded dynamically (e.g., inside a dropdown menu) and might not be detected by the plugin otherwise.

To do this, add a data-cv-page-local-toggles attribute to any element (an empty <div> is a good choice). The value of this attribute should be a comma-separated list of the local toggle IDs you want to register.

For example, to make the local toggles with IDs advanced and dark-mode available in the settings, add the following to your page:

<div data-cv-page-local-toggles="advanced, dark-mode"></div>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

This will ensure that the specified local toggles appear in the configuration settings, allowing users to control them even if they are not immediately visible on the page.

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.