Components

ToggleButtonsGroupField

Form field component for selecting options using a group of toggle buttons.

Component

View code

Show playground

Label

Help text example

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	—	`string`
`helpText`	—	—	`string`
`helpTextPosition`	—	`Position.BOTTOM`	`Position`
`buttons`	—	`ToggleButton[]`	`array`
`modelValue`	`true`	—	`string`
`onlyIcon`	—	`false`	`boolean`
`groupStyle`	—	—	`ToggleButtonGroupStyle`
`size`	—	`ButtonSize.LG`	`ButtonSize`
`disabled`	—	`false`	`boolean`
`transparent`	—	`false`	`boolean`

Usage

id

Sets the id of the field.

 <template>
    <ToggleButtonsGroupField id="field-id" />
</template>

Type: string
Required: true

label

Sets the label of the field.

 <template>
    <ToggleButtonsGroupField label="Example label text" />
</template>

Type: string

helpText

Sets the help text of the field.

 <template>
    <ToggleButtonsGroupField helpText="This is an example help text." />
</template>

Type: string
Default: ''

helpTextPosition

Sets the position of the help text relative to the field. It uses the Position enum.

 <template>
    <ToggleButtonsGroupField helpTextPosition="top" helpText="Appears above the field" />
</template>

Type: Position
Default: Position.BOTTOM

Options

Value	Description
`TOP`	top
`BOTTOM`	bottom

buttons

Sets the buttons options of the field. Use two buttons for the toggle behavior.

Buttons can be of type ToggleButton or ToggleIconButton. The first one includes a text and an optional icon, while the second one is only an icon button.

Using TogggleButton array

 <template>
    <ToggleButtonsGroupField :buttons="exampleButtons" />
</template>
<script setup lang="ts">
const exampleButtons = ref<ToggleButton[]>([
    { text: 'Option 1', value: 'option1' },
    { text: 'Option 2', value: 'option2' },
])
</script>

Using TogggleIconButton array

 <template> 
    <ToggleButtonsGroupField 
        :buttons="exampleIconButtons" 
        onlyIcon 
    /> 
</template> 
<script setup lang="ts">
const exampleIconButtons = ref<ToggleIconButton[]>([ 
    { icon: 'mdi:arrow-up', value: 'Newest', ariaLabel: 'Sort by newest' }, 
    { icon: 'mdi:arrow-down', value: 'Oldest', ariaLabel: 'Sort by oldest' }, 
]) 
</script>

Type: ToggleButton[] | ToggleIconButton[]

 export interface BaseToggleButton {
    value: string
    ariaLabel?: string
    active?: boolean
    action?: () => void
    size?: ButtonSize
    icon?: string
}

export interface ToggleButton extends BaseToggleButton {
    text: string
    iconPosition?: IconPosition
}

export type ToggleIconButton = BaseToggleButton

export type ToggleButtonItem = ToggleButton | ToggleIconButton

For icon-only buttons (ToggleIconButton[]), set ariaLabel on each item so every button has an accessible name.

modelValue

Sets the selected value of the field.

 <template>
    <ToggleButtonsGroupField v-model="selectedValue" />
</template>
<script setup lang="ts">
const selectedValue = ref<string>('option1')
</script>

Type: string
Required: true

onlyIcon

When using icon buttons, this prop determines whether to display only the icons or also the text (if available).

     <template> 
        <ToggleButtonsGroupField 
            :buttons="exampleIconButtons" 
            onlyIcon 
        /> 
    </template> 
<script setup lang="ts"> 
const exampleIconButtons = ref<ToggleIconButton[]>([ 
    { icon: 'mdi:arrow-up', value: 'Newest' }, 
    { icon: 'mdi:arrow-down', value: 'Oldest' }, 
]) 
</script>

Type: boolean
Default: false

groupStyle

Sets the style of the toggle buttons group.

 <template>
    <ToggleButtonsGroupField :groupStyle="ToggleButtonGroupStyle.GROUPED" />
</template>

Type: ToggleButtonGroupStyle

Options

Value	Description
`GROUPED`	Grouped style
`SEGMENTED`	Segmented style

size

Sets the default size applied to buttons in the group. If a button in the buttons array sets its own size, that value takes precedence over this prop (see buttons).

 <template>
    <ToggleButtonsGroupField :size="ButtonSize.XL" />
</template>

Type: ButtonSize
Default: ButtonSize.LG

Options

Value	Description
`XS`	xs
`SM`	sm
`MD`	md
`LG`	lg
`XL`	xl
`XXL`	2xl

disabled

Sets the disabled state of the field.

 <template>
    <ToggleButtonsGroupField disabled />
</template>

Type: boolean
Default: false

transparent

Removes the background fill from each toggle button, making them transparent.

 <template>
    <ToggleButtonsGroupField transparent />
</template>

Type: boolean
Default: false