DOM Studio

Component

Toggle button group

<DomToggleButtonGroup>

A single or multiple selection button group for compact form choices.

Playground

Try every prop live

Toggle button group playground

Use single mode as a segmented control, or multiple mode for independent pressed options.

Playground.vuevue
vue
<script setup>
import { reactive } from 'vue';
import { DomToggleButtonGroup } from '@getdom/studio/vue';

const data = reactive({
	  "modelValue": "grid",
	  "id": "",
	  "name": "",
	  "label": "View",
	  "description": "",
	  "placeholder": "",
	  "required": false,
	  "disabled": false,
	  "readOnly": false,
	  "invalid": false,
	  "errors": [],
	  "visible": true,
	  "validators": [],
	  "validateOnBlur": true,
	  "chrome": "field",
	  "options": [
	    {
	      "label": "List",
	      "value": "list",
	      "tooltip": ""
	    },
	    {
	      "label": "Grid",
	      "value": "grid",
	      "tooltip": ""
	    },
	    {
	      "label": "Board",
	      "value": "board",
	      "tooltip": ""
	    }
	  ],
	  "type": "single",
	  "orientation": "horizontal",
	  "size": "md",
	  "variant": "default"
	});
</script>

<template>
	<DomToggleButtonGroup
		v-bind="data"
		@update:modelValue="data.modelValue = $event"
	/>
</template>

Demo

Single and multiple modes

Single mode returns one value. Multiple mode returns an array of pressed values.

Single mode behaves like a segmented control.

Multiple mode lets users keep more than one option pressed.

{
  "view": "grid",
  "tools": [
    "comments"
  ]
}
ViewMode.vuevue
vue
<script setup>
import { ref } from 'vue';
import { DomToggleButtonGroup } from '@getdom/studio/vue';

const view = ref('grid');
const tools = ref(['comments']);

const views = [
	{ label: 'List', value: 'list' },
	{ label: 'Grid', value: 'grid' },
	{ label: 'Board', value: 'board' },
];

const viewIcons = [
	{ label: 'List', value: 'list', tooltip: 'List view', ariaLabel: 'List view', icon: 'M8 6h12M8 12h12M8 18h12M4 6h.01M4 12h.01M4 18h.01' },
	{ label: 'Grid', value: 'grid', tooltip: 'Grid view', ariaLabel: 'Grid view', icon: 'M7 7h4v4H7V7Zm6 0h4v4h-4V7ZM7 13h4v4H7v-4Zm6 0h4v4h-4v-4Z' },
];

const toolOptions = [
	{ label: 'Comments', value: 'comments' },
	{ label: 'Activity', value: 'activity' },
	{ label: 'Files', value: 'files' },
];
</script>

<template>
	<div class="space-y-5">
		<DomToggleButtonGroup
			v-model="view"
			label="View"
			:options="views"
			description="Single mode behaves like a segmented control."
		/>

		<DomToggleButtonGroup
			v-model="view"
			:options="viewIcons"
			label="Display"
			chrome="none"
			size="icon-lg"
			variant="switch"
		>
			<template #option="{ option }">
				<svg viewBox="0 0 24 24" class="size-5" fill="none" aria-hidden="true">
					<path :d="option.icon" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" />
				</svg>
				<span class="sr-only">{{ option.label }}</span>
			</template>
		</DomToggleButtonGroup>

		<DomToggleButtonGroup
			v-model="tools"
			type="multiple"
			label="Panels"
			:options="toolOptions"
			description="Multiple mode lets users keep more than one option pressed."
		/>

		<pre class="overflow-auto rounded-xl border border-border bg-secondary/30 p-3 text-xs text-muted-fg">{{ { view, tools } }}</pre>
	</div>
</template>

Reference

Props

Control props

NameTypeTSDefaultDescription
modelValuestring | number | arrayArray<unknown>''Selected value for single mode, or selected values for multiple mode.
options*
ts
[
	{
		label: "Option 1",
		value: "option-1",
		tooltip: "Choose this option",
	}
]
arrayArray<OptionsItem
type OptionsItem = {
	label?: string; // Label
	value?: string; // Value
	tooltip?: string; // Tooltip
};
>		—Toggle button options.
type'single' | 'multiple'string'single'Allow one selection or many.
orientation'horizontal' | 'vertical'string'horizontal'Visual direction and arrow key behaviour.
size'sm' | 'md' | 'lg' | 'icon-sm' | 'icon-md' | 'icon-lg'string'md'Button size.
variant'default' | 'switch'string'default'Visual treatment. Use switch for raised icon-only segmented controls.

Field props

NameTypeTSDefaultDescription
idstringstring''Optional ID override. By default parent forms derive the input ID from the field path using underscores.
namestringstring''Local field name. Parent forms derive the full field path and native HTML name from the form hierarchy.
labelstringstring''Visible field label.
descriptionstringstring''Optional helper copy below the field.
placeholderstringstring''Placeholder shown when the control is empty.
requiredbooleanbooleanfalseMark the field as required.
disabledbooleanbooleanfalseDisable field interaction.
readOnlybooleanbooleanfalseShow the value but prevent editing.
invalidbooleanbooleanfalseMark the field invalid.
errors
ts
[
	{
		name: "Validation name",
		message: "Error message",
	}
]
array | object | stringArray<ErrorsItem
type ErrorsItem = {
	name?: string; // Name
	message?: string; // Message
};
>		[]Validation errors for this field.
visiblebooleanbooleantrueShow or hide the field.
validatorsarrayArray<unknown>[]Validators attached to this field. Use functions in Vue code, or serializable records such as { name: "minLength", props: { min: 2 } } in generated schemas.
validateOnBlurbooleanbooleantrueRun validators when the field loses focus.
chrome'field' | 'none' | falsestring'field'Render default field chrome, or hide chrome while keeping form state wiring.

Auto-generated from Toggle button group.props and inline _edit hints.

Events

NamePayloadDescription
@update:modelValue(value
value: string | string[];
: string | string[])		Emitted when selection changes.
@focus——
@blur——

Names auto-detected from defineEmits and source emit() calls; payload and description from __doc.events when present.