An individual toggle button. When activated it toggles between pressed and unpressed states.

Tag

<lustre-toggle>

Attributes

default_pressed, disabled, pressed, value.

Events

on_press.

Styling

This element has a default display of inline.

The following CSS custom states can be used to style this element:

• :state(pressed) is applied when the toggle is pressed.
• :state(disabled) is applied when the toggle is disabled.

Accessibility notes

A toggle can receive focus and be activated using the keyboard by pressing either the Enter or Space keys.

The toggle must have an accessible text label for non-sighted uses. This can be text content inside the toggle element itself, an associated <label> for toggles used in forms, or an aria-label attribute.

Managed attributes

The following attributes must not be set manually on the element, as these are managed by the component and are necessary for accessibility:

• aria-disabled
• aria-pressed
• role

A group of toggle buttons. Only one toggle may be pressed at a time.

Tag

<lustre-toggle>

Attributes

default_pressed, disabled, loop, pressed, value.

Events

on_selected_change.

Styling

This element has a default display of inline.

The following CSS custom states can be used to style this element:

• :state(disabled) is applied when the entire group is disabled.

Accessibility notes

The toggle group supports keyboard navigation between individual toggles using the following keys instead of to the standard tabbing behaviour:

• When in a vertical group...
  • Arrow Up moves focus to the previous toggle.
  • Arrow Down moves focus to the next toggle.
• When in a horizontal group...
  • Arrow Left moves focus to the previous toggle.
  • Arrow Right moves focus to the next toggle.

Managed attributes

The following attributes must not be set manually on the element, as these are managed by the component and are necessary for accessibility:

• aria-orientation
• role

An individual toggle as part of a group. Each item should have a unique value in the group: empty or duplicate values will be ignored.

For more detailed documentation, refer to the toggle.view element.

Disable a toggle or toggle group. Disabled toggles cannot be interacted with and should be styled appropriately to communicate this to sighted users. When a group is disabled, the user will still be able to navigate to each item using the keyboard, but they will not be able to activate any of the items.

Set whether an individual toggle is pressed when it is first rendered. This is only useful for uncontrolled toggles or for server-side rendering. To control the pressed state of a toggle in your app, use the pressed attribute instead.

Note: an uncontrolled component is responsible for managing its own state and subsequent changes to default_pressed will not be reflected in the component after the initial render.

To control the toggle component's state from your application, use the pressed attribute instead.

Sets the pressed state for a controlled toggle.

Note: in a controlled component, the state is managed by your application and must be updated in response to user interaction by handling the on_press event.

To let the component manage its own state, use the default_pressed attribute to set the initial pressed state of a toggle instead.

Sets the value to be included in form submission for a pressed toggle. If this attribute is not set, a toggle behaves like a HTML checkbox input and sends the value "on" when pressed.

Set the default selected item in a toggle group by value. This is only useful for uncontrolled groups or for server-side rendering. To control the selected item in your app, use the selected attribute instead.

Set the selected item in a controlled toggle group by its value, or None to clear any selection.

Note: in a controlled component, the state is managed by your application and must be updated in response to user interaction by handling the on_selected_change event.

When True, the loop attribute allows users to cycle through the toggle items in a group by navigating past the first or last item using the keyboard.

Note: be mindful of the accessibility implications of this attribute. If the toggle group exists inside another container that also relies on keyboard navigation, like a menu or toolbar, you may trap users inside the toggle group by enabling looping.

An event emitted by individual toggles when they are pressed.

Note: like other DOM events, this event bubbles and can be listened for on a parent toggle group.

This event is emitted by a toggle group when any of its child items are pressed. The provided handler is called with either the value of the pressed item, or None if an already-selected item is deselected.