CSS Toggles

1. Introduction

This section is not normative.

Many user-interface languages define elements which can have "toggleable state", which can be modified by user interaction and responded to by the element. For example, in HTML, the <input type=checkbox> has a "checked" state which toggles between true and false when the user activates the element, and which is selected by the :checked pseudoclass.

These sorts of elements are extremely useful, to the point that authors sometimes abuse them to get the same functionality on other elements:

<ul class='ingredients'>
  <li><label><input type=checkbox><span>1 banana</span></label>
  <li><label><input type=checkbox><span>1 cup blueberries</span></label>
  ...
</ul>
<style>
input[type='checkbox'] {
  display: none;
}
input[type='checkbox']:checked + span {
  color: silver;
  text-decoration: line-through;
}
</style>

This module generalizes this ability and allows it to be applied to any element via CSS, so authors do not have to abuse host language semantics for styling purposes. It defines a a way of attaching lightweight "state" to an element via CSS (toggle-root), defining how user interactions can change that state (toggle-trigger), and responding to that state from CSS (:toggle() pseudo-class). Scripting can also create, modify, and respond to this state, to accommodate more complicated scenarios.

It also defines how to infer reasonable accessibility semantics from the toggle structure, making it simpler and more reliable to produce accessible pages using these sorts of basic interactivity without the author having to manually annotate a page with ARIA attributes or similar.

1.1. Terminology

Any element can become a toggle root, meaning it hosts one or more toggles. Each toggle has a name, a value between 0 and some maximum, and a few other bits of metadata, all of which can be set via the toggle-root property. The toggle is visible to the toggle root, its descendants, and possibly its siblings and their descendants (if the toggle says they can); any element that can "see" a toggle can use the :toggle() pseudo-class to select the element based on the toggle’s value.

Any element that can see a toggle can also trigger the toggle, changing its value when the element is "activated", via the toggle-trigger property. This means you can have elements that self-trigger their own toggle, like checkboxes, but also have toggles that are visible to wide sections of a page and are triggered by buttons (or tabs, or headings, etc) inside that section, so multiple elements can use :toggle() to respond to the toggle.

Toggles can also be grouped together, so that only one of the toggles in the group can have a non-zero value at a time, like how radio buttons work in HTML.

2. Toggle Concepts

A toggle is a struct associated with an element, which represents something that can be toggled on or off by user action, and matched with Selectors. Toggles have the following items:

name

A <dashed-ident>.

value

A <custom-ident> or non-negative <integer>: either 0 (the inactive value) or a value 1 or higher (the active values).

states

Either an integer greater than or equal to 1, indicating the nominally maximum integer value, or a list of unique state names, each of which are <custom-ident>s.

This also defines the maximum state of a toggle, as either the states value (if it’s an integer) or the length of states minus 1 (if it’s a list).

Note: Toggles can be set to integer values larger than than the "maximum", or to ident values not given in the list of names, but when a toggle is incremented or decremented it will treat all such values as out-of-bounds and bring the value back within the range defined by states.

group

A boolean indicating whether the toggle is part of a toggle group (of the same name) or not.

scope

An enum indicating what sort of scope the toggle uses. It can have two values:

• "wide", indicating the toggle has wide scope (it’s visible to the element, its descendants, and its following siblings and their descendants).

• "narrow", indicating the toggle has narrow scope (it’s visible to the element and its descendants only).

overflow

An enum (either "cycle", "cycle-on" or "sticky"), specifying how to react when a toggle activation would increment the value above its maximum or below its minimum.

The precise details are defined in change a toggle, but in short:

• For cycle, incrementing past the maximum resets the value to 0, and decrementing below 0 resets it to the maximum.

• For cycle-on, incrementing past the maximum resets the value to 1, and decrementing it below 1 resets it to the maximum.

  (In other words, the toggle "stays on" once it reaches an active value, rather than cycling back to an inactive value.)

• For sticky, incrementing past the maximum value resets the value to the maximum, and decrementing it below 0 resets it to 0.

Toggles are persistent state on an element. Once created, none of their items are affected by CSS, and only their value can be changed by user interaction. (Scripting can change the other items, however; see § 6 Scripting API.) An element can have any number of toggles.

A toggle specifier is a struct associated with an element, with the same structure as a toggle. They serve multiple roles: they specify what toggles the element is expected to have on it (creating fresh ones if they don’t exist), provide default values for the newly-created toggle’s items, and override a toggle’s default behavior when it receives a toggle activation.

Toggle specifiers are defined by the toggle-root property; they are not persistent state on the element. An element can have any number of toggle specifiers.

A toggle group is a struct associated with an element, which groups together toggles of the same name so that only one can be in an active value at a time. Toggle groups have the following items:

name

A <dashed-ident>.

scope

An enum indicating what sort of scope the toggle group uses. It can have two values:

• "wide", indicating the toggle has wide scope (it’s visible to the element, its descendants, and its following siblings and their descendants).

• "narrow", indicating the toggle has narrow scope (it’s visible to the element and its descendants only).

Toggle groups are defined by the toggle-group property; they are not persistent state on an element. An element can have any number of toggle groups.

A toggle is in a toggle group if its group boolean is true; if the element is in scope for a toggle group with the same name as the toggle, it’s in that group; otherwise, it’s in a document-wide implicit toggle group with the same name.

Toggles and toggle groups have a scope, defining what additional elements (beyond the element the toggle/toggle group is on) can see and interact with the toggle/toggle group.

If the toggle (toggle group) has wide scope, it’s visible to the element it’s defined on, its descendants its following siblings, and their descendants.

If the toggle (toggle group) has narrow scope, it’s visible to the element it’s defined on and its descendants.

Toggles of the same name "shadow" earlier ones; if multiple toggles of a given name would have overlapping scopes, an element is only in scope for the toggle created by the nearest preceding element in tree order. The same applies to toggle groups. However, toggles and toggle groups do not interfere with each other’s scopes; an element can "see past" a toggle to find a toggle group of the same name it’s in scope for, and vice versa.

2.1. Toggles and CSS Properties

To allow for toggles to be responded to by Selectors without causing any circularity issues, toggles themselves are invisible state on an element, separate from any CSS properties that might apply. The CSS properties merely define which elements can activate a toggle, and which elements can respond to a toggle activation (and how they do so).

.toggleable {
  toggle-root: --foo 1;
  toggle-trigger: --foo;
}
.toggleable:toggle(--foo) {
  toggle-root: none;
  toggle-trigger: none;
}

3. Creating a Toggle: the toggle-root property

<toggle-specifier> =
  <dashed-ident>
  [
    <toggle-states> [at <toggle-value>]? ||
    <toggle-overflow> ||
    group ||
    self
  ]?
<toggle-states> = <integer [1,∞]> | '[' <custom-ident>{2,} ']'
<toggle-value> = <integer [0,∞]> | <custom-ident>
<toggle-overflow> = cycle | cycle-on | sticky

The toggle-root property causes toggles to be created on an element, and controls how the toggles are updated when they are activated.

none

The element has no toggle specifiers.

(This does not remove any toggles that have already been established on the element.)

<toggle-specifier>#

The element has one or more toggle specifiers, one per <toggle-specifier>, which determine how toggles will be initially created if they don’t already exist on the element, and how they react to being activated.

Each <toggle-specifier> is composed of several parts, most of which are optional, corresponding to the items of a toggle specifier. They specify how the newly-created toggle will be set up:

• The initial <dashed-ident> specifies the name.

• The <toggle-states> specifies the states. If specified as an <integer>, it sets states to the given number; if specified as a bracketed list of <custom-ident>s, it sets states to a list containing those identifiers. If omitted, defaults to 1.

  If <toggle-states> is a bracketed list, and there are any repeated <custom-ident>s among its items, the property is invalid.

• The <toggle-value>, if specified, specifies the initial value. If omitted, it’s set to 0.

• The <toggle-overflow> keyword, if specified, specifies the overflow enum. If omitted, it’s set to "cycle".

• The group keyword, if specified, sets the group boolean to true. If omitted, it’s set to false.

• The self keyword, if specified, sets the scope enum to "narrow". If omitted, it’s set to "wide".

In addition to specifying how to create new toggles, a toggle specifier overrides the existing toggle’s states, overflow, and group, if they differ, allowing an existing toggle to have its behavior changed if necessary.

<ul class='ingredients'>
  <li>1 banana
  <li>1 cup blueberries
  ...
</ul>
<style>
li {
  toggle: --check self;
}
li:toggle(--check) {
  color: silver;
  text-decoration: line-through;
}
</style>

3.1. Toggle Creation Details

Each element has a list of established toggles, representing toggles on the element. These are created automatically by the toggle-root property, and/or manually by interacting with the Element.toggles map.

Define the precise point in update the rendering when toggles are created if toggle-root names a toggle that doesn’t exist on the element yet.

3.2. Linking Toggle Values: the toggle-group property

By default, each toggle’s value is independent; incrementing one has no effect an any other. The toggle-group property allows elements to link their toggles together: all toggles with the same name as the toggle group that are on elements in scope for the toggle group are linked, such that only one can be in an active value at a time, similar to HTML’s <input type=radio> element.

none

The element does not define a toggle group.

[<dashed-ident> self?]#

The element defines one or more toggle groups, one per comma-separated item:

• The <dashed-ident> specifies the name, as the item’s value.

• The self keyword, if specified, sets the scope enum to "narrow". If omitted, it’s set to "wide".

Only one toggle in a toggle group can be in an active value at a time; see toggle-trigger for details.

<panel-set>
  <panel-tab>first tab</panel-tab>
  <panel-card>first panel</panel-card>
  <panel-tab>second tab</panel-tab>
  <panel-card>second card</panel-card>
  ...
</panel-set>
<style>
panel-set {
  /* The common ancestor sets up a group */
  toggle-group: --tab;
}
panel-tab {
  /* Each tab creates a cycle-on toggle
    (so once it's open, clicking again won't close it),
    opts into the group,
    and declares itself a toggle activator */
  toggle: --tab 1 group cycle-on;
}
panel-tab:first-of-type {
  /* The first tab also sets its initial value
    to be active */
  toggle: --tab 1 at 1 group cycle-on;
}
panel-tab:toggle(--tab) {
  /* styling for the active tab */
}
panel-card {
  /* cards are hidden by default */
  display: none;
}
panel-card:toggle(--tab) {
  display: block;
}
</style>

3.3. Activating a Toggle: the toggle-trigger property

<toggle-trigger> = <dashed-ident> <trigger-action>?
<trigger-action> =
  [prev | next] <integer [1,∞]>? |
  set <toggle-value>

The toggle-trigger property specifies that an element can be activated to change the value of one or more toggles. It has the following values:

Consider adding support for an at-rule that defines machine states, the available events to trigger from each state, and the resulting state of each event. In that case <trigger-action> would need to also accept custom events, possibly marked by a new keyword or function.

none

The element does not manipulate any toggles.

<toggle-trigger>

If the <trigger-action> is omitted, it defaults to next 1. If the <trigger-action> specifies prev or next, but omits the following <integer>, it defaults to 1.

If the element already has existing activation behavior from the host language, this value does nothing.

Otherwise, the element becomes activatable, and when activated, for each comma-separated entry in the list, fires a toggle activation with the given <dashed-ident> as a name, and the <trigger-action> action.

A toggle activation is a struct with the following items:

name

The name of the toggle this is intended to activate.

action

A <trigger-action> value.

Define in much greater precision what it means to "become activatable". The element must become focusable (with a default spot in the focus order) and become capable of being activated by mouse/keyboard/etc. Similarly define the "already activatable" prose in more detail; we want to exclude things like text inputs, which would confuse a11y tooling, but include buttons that aren’t, like, submit buttons.

3.4. Creating and Activating Toggles Simultaneously: the toggle shorthand

While some cases require setting up a toggle on an ancestor of the elements that will activate and respond to the toggle, in many cases the scope rules for toggles are such that it’s fine to create the toggle on the element intended to activate the toggle as well.

The toggle shorthand sets both the toggle-root and toggle-trigger properties on an element together. The entire value of the property is assigned to toggle-root, while toggle-trigger is assigned to just the <dashed-ident>s specified in the list, if any.

<spoiler-text>
  <summary>...</summary>
  <content>...</content>
</spoiler-text>
<style>
  spoiler-text > summary {
    toggle: --show;
  }
  spoiler-text > content {
    toggle-visibility: --show;
  }
</style>

3.5. Accessibility Implications of Toggles

4. Selecting Elements Based on Toggle Value: the :toggle() pseudo-class

[SELECTORS-4] defines the :checked pseudo-class, which allows author to match certain elements (as defined by the host language) depending on their "checked" state.

Toggles provides a very similar functionality, allowing elements to be selected based on their toggle value, the :toggle() pseudo-class:

:toggle( <dashed-ident> <toggle-value>? )

An element matches :toggle() if the element is in scope for a toggle with the name given by <dashed-ident>, and either the toggle matches the provided <toggle-value>, or the <toggle-value> is omitted and the toggle is in any active value.

.ingredient {
  toggle: --used;
}
.ingredient:toggle(--used) {
  color: silver;
  text-decoration: line-through;
}

.tristate-check {
  toggle: --check 2 at 0;
}
.tristate-check:toggle(--check 1) {
  /* "checked" styles */
}
.tristate-check:toggle(--check 2) {
  /* "indeterminate" styles */
}

.card:toggle(--show 0) {
  /* Definitely *not* shown */
}

5. Automatically Hiding With A Toggle

The content-visibility property allows an element to suppress the layout and rendering of its contents, similar to display: none; however, its auto value allows the contents to still be visible to various searching and accessibility features, like find-in-page, hash-navigation, or tab order, and then to automatically become visible when the element becomes relevant to the user.

A common use-case for toggles is also to control whether an element is shown or hidden, and in many cases it would also be useful to allow the contents of elements "hidden" in this way to be accessible in the same ways. To allow for this, the toggle-visibility property allows an element to both respond to and control a toggle with its visibility.

The toggle-visibility property allows an element to automatically tie its display to a particular toggle bi-directionally, while still exposing its contents to be focused, found-in-page, etc., automatically showing itself when relevant.

normal

The property has no effect.

<dashed-ident>

If the element is in scope for a toggle whose name matches the <dashed-ident>, and that toggle is in the inactive value, then the element acts as if content-visibility: auto is specified, except that being on-screen does not make it relevant to the user.

If the element starts being relevant to the user, it fires a toggle activation, with a name of the given <dashed-ident> and a action of set 1.

Note: If the toggle is in an active value, or the element can’t see the specified toggle at all, the element renders normally.

<dl class=accordion>
  <dt>Question 1?
  <dd>Long answer......
  <dt>Question 2?
  <dd>Another long answer.....
</dl>
<style>
  .accordion > dt {
    toggle: --show;
  }
  .accordion > dd {
    toggle-visibility: --show;
  }
</style>

Define ordering of activations, so if multiple elements become relevant at the same time and they’re all part of a toggle group, which one "wins" is well-defined.

6. Scripting API

6.1. CSSToggleMap

partial interface Element {
  [SameObject] readonly attribute CSSToggleMap toggles;
};

interface CSSToggleMap {
  maplike<DOMString, CSSToggle>;
  CSSToggleMap set(DOMString key, CSSToggle value);
};

The toggles attribute on Elements represents the established toggles on the element: each toggle is represented by an entry in the map, with its key equal to its name and its value a CSSToggle representing the rest of the toggle’s data.

Entries can be automatically added to toggles by the toggle-root property when update the rendering occurs, if toggle-root defines a toggle specifier whose name doesn’t exist in toggles yet; see § 3.1 Toggle Creation Details for details.

6.2. CSSToggle

interface CSSToggle {
  attribute (unsigned long or DOMString) value;
  attribute unsigned long? valueAsNumber;
  attribute DOMString? valueAsString;

  attribute (unsigned long or FrozenArray<DOMString>) states;
  attribute boolean group;
  attribute CSSToggleScope scope;
  attribute CSSToggleCycle cycle;

  constructor(optional CSSToggleData options);
};

dictionary CSSToggleData {
  (unsigned long or DOMString) value = 0;
  (unsigned long or sequence<DOMString>) states = 1;
  boolean group = false;
  CSSToggleScope scope = "wide";
  CSSToggleCycle cycle = "cycle";
};

enum CSSToggleScope {
  "narrow",
  "wide",
};

enum CSSToggleCycle {
  "cycle",
  "cycle-on",
  "sticky",
};

A CSSToggle represents a toggle; changing any attribute on the CSSToggle will change the corresponding items of the toggle it represents, and vice versa.

Note: Only the value will change directly on a toggle and get reflected back to the CSSToggle; the rest of its items are fixed on creation unless manually changed on its associated CSSToggle.

A CSSToggle will usually be an established toggle on an element, present in the element’s toggles attribute, but can also be used independently. This is tracked by a [[ToggleMap]] internal slot, containing either undefined (the initial value) or a weak reference to the CSSToggleMap the CSSToggle is in.

6.3. CSSToggleEvent

interface CSSToggleEvent : Event {
  constructor(DOMString type, optional CSSToggleEventInit eventInitDict = {});
  readonly attribute DOMString toggleName;
  readonly attribute CSSToggle? toggle;
};

dictionary CSSToggleEventInit : EventInit {
  DOMString toggleName = "";
  CSSToggle? toggle = null;
};

whatwg/dom#600 means apparently events don’t yet work if their init dictionaries have required members. Neither of these have reasonable defaults, especially the toggle part, but oh well I guess.