Button Toggles

Example

Basic Button Toggle

This example demonstrates a simple button toggle component with two text-based options. The component uses the mandatory property to ensure that one option is always selected. Rounded corners are applied and a custom color are used to highlight the selected state. This setup is useful for basic binary choices such as theme switching or mode selection.

import "spatial-design-system/primitives/ar-button-toggle.js";

<a-ar-buttontoggle
    position="0 1.6 -1"
    buttons='[
        {"label": "LIGHT"},
        {"label": "DARK"}
    ]'
    rounded="true"
    size="medium"
    mandatory="true"
    color="#03FCC6"
></a-ar-buttontoggle>

Icon Options Button Toggle

This example shows a button toggle component that uses icons instead of text labels. Each button is defined with an icon reference, creating a compact and visually driven control suitable for toolbars or alignment actions.

import "spatial-design-system/primitives/ar-button-toggle.js";

<a-ar-buttontoggle
    position="0 1.6 -1"
    buttons='[
        {"icon": "/align-left.png"},
        {"icon": "/align-center.png"},
        {"icon": "/align-right.png"}
    ]'
    size="medium"
    color="#018A6C"
    multiple="true"
></a-ar-buttontoggle>

Text & Icon Options Button Toggle

This example demonstrates an advanced button toggle configuration combining both text labels and icons with custom actions. Each button includes a label, an icon positioned on the right side, and an associated action that is emitted when selected. The component uses a tile shape, resulting in square edges instead of rounded corners. The mandatory property ensures that at least one button remains selected at all times, with the first button selected by default. Because multiple is set to false, only one button can be active at a time. Selecting another option automatically switches the active state.

import "spatial-design-system/primitives/ar-button-toggle.js";

<a-ar-buttontoggle
    position="0 1.6 -1"
    buttons='[
        {"label": "LEFT", "icon": "/align-left.png", "iconpos": "right", "action": "aligntoleft"},
        {"label": "CENTER", "icon": "/align-center.png", "iconpos": "right", "action": "aligncenter"},
        {"label": "RIGHT", "icon": "/align-right.png", "iconpos": "right", "action": "aligntoright"}
    ]'
    tile="true"
    size="medium"
    mandatory="true"
    multiple="false"
    color="#03FCC6"
></a-ar-buttontoggle>

Props

Property	Type	Default	Description
visible	boolean	true	Determines whether the button toggle group is displayed.
position	number[]	0 0 0	Specifies the component's position.Defines the component’s position in 3D space as an array of coordinates.
size	enum (small, medium, large, extra-large)	medium	Controls the size of all toggle buttons, including padding, font size, and spacing.
opacity	number	1	Sets the transparency level of the component.
color	string (blue, #fff)	#00BA92	Defines the color applied to selected buttons. Unselected buttons use a neutral style by default (white background and black text color).
mode	string (light, dark)	""	Applies a light or dark visual theme to selected buttons for consistent styling.
buttons	array	[{ label: "Close", icon: "", iconpos: "left", action: "close" }]	Defines the buttons displayed in the toggle group. Each button may include a label, icon, icon position, and action. When selected, a buttonAction event is emitted with the associated action value.
mandatory	boolean	false	Ensures that at least one button remains selected at all times.
multiple	boolean	false	Allows multiple buttons to be selected simultaneously when enabled.
rounded	boolean	false	Applies rounded corners to the entire toggle group. Takes precedence over the tile property.
tile	boolean	false	Renders the toggle group with square edges instead of rounded corners.