ToggleButton
A ToggleButton is a button that can be toggled on and off.
Guidelines
Using toggle buttons
Toggle buttons feature a normal and an “on” state. They generally contain a label and can also include an icon. For icon-only buttons, the label will be visually hidden while still available to screen reader users.
There are two types of toggle buttons: normal and quiet. There is no toggle button variant designed for progressive or destructive actions.
Use the ToggleButton component for options that require state persistence and are longer or more involved than a typical button click action. Avoid using ToggleButton if you need to trigger an immediate action or toggle something within the current user context; in this case use a Button instead.
Specifications
ToggleButton may include the following elements:
- Icon (optional)
Icons simplify user recognition and provide the ability to shorten button labels to a minimum. - Label
Button labels should be as short as possible, with text that clearly states what state is changed when toggling the button (eg. show/hide). Note that the label text should not change depending on the button’s toggled state.
Types
Depending on the style of the button, there are two types of toggle buttons:
- Normal toggle buttons. They are the default choice for simplified recognition.
- Quiet toggle buttons (frameless). Only use quiet toggle buttons for an easily recognizable action that does not detract focus from the content.
Depending on the button's content, it can have one of the following formats:
- Icon and text
- Text-only
- Icon-only
Interaction states
Buttons have the following visually separate states:
Neutral buttons
Quiet buttons
- Toggled-off default
- Toggled-off hover
- Toggled-off active
- Toggled-off focus
- Toggled-off disabled
- Toggled-on default
- Toggled-on hover
- Toggled-on active
- Toggled-on focus
- Toggled-on disabled
Demos
Configurable
<cdx-toggle-button v-model="buttonValue">Button text</cdx-toggle-button>
Name | Value |
---|---|
Props | |
disabled | |
quiet | |
Slots | |
default | |
View | |
Reading direction |
Default
Press the ToggleButton to see the value change. Open up the console to see emitted events.
ToggleButtons should always have a static label. This helps indicate to the user (including users of assistive technology) what it means for the button to be on or off. If you want a button with a label that changes when it is pressed, use the Button component instead.
Toggle button value: false
<template>
<div>
<p class="cdx-docs-demo-text">
Toggle button value: {{ buttonValue }}
</p>
<cdx-toggle-button
v-model="buttonValue"
@update:model-value="onUpdate"
>
<cdx-icon :icon="cdxIconPlay" />
Play
</cdx-toggle-button>
</div>
</template>
<script>
import { defineComponent, ref } from 'vue';
import { CdxToggleButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconPlay } from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'SingleButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
const onUpdate = function ( value ) {
// eslint-disable-next-line no-console
console.log( 'update:modelValue event emitted with value: ' + value );
};
return {
buttonValue,
onUpdate,
cdxIconPlay
};
}
} );
</script>
<template>
<div>
<p class="cdx-docs-demo-text">
Toggle button value: {{ buttonValue }}
</p>
<cdx-toggle-button
v-model="buttonValue"
@update:model-value="onUpdate"
>
<cdx-icon :icon="cdxIconPlay"></cdx-icon>
Play
</cdx-toggle-button>
</div>
</template>
<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxToggleButton, CdxIcon } = require( '@wikimedia/codex' );
const { cdxIconPlay } = require( './icons.json' );
// @vue/component
module.exports = defineComponent( {
name: 'SingleButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
const onUpdate = function ( value ) {
// eslint-disable-next-line no-console
console.log( 'update:modelValue event emitted with value: ' + value );
};
return {
buttonValue,
onUpdate,
cdxIconPlay
};
}
} );
</script>
Icon only
When the ToggleButton includes only an icon and no text, add an aria-label
to the ToggleButton to ensure the button is understandable to those using assistive technology.
<template>
<div>
<cdx-toggle-button
v-model="buttonValue"
aria-label="Play"
>
<cdx-icon :icon="cdxIconPlay" />
</cdx-toggle-button>
</div>
</template>
<script>
import { defineComponent, ref } from 'vue';
import { CdxToggleButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconPlay } from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'IconOnlyButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
return {
buttonValue,
cdxIconPlay
};
}
} );
</script>
<template>
<div>
<cdx-toggle-button
v-model="buttonValue"
aria-label="Play"
>
<cdx-icon :icon="cdxIconPlay"></cdx-icon>
</cdx-toggle-button>
</div>
</template>
<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxToggleButton, CdxIcon } = require( '@wikimedia/codex' );
const { cdxIconPlay } = require( './icons.json' );
// @vue/component
module.exports = defineComponent( {
name: 'IconOnlyButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
return {
buttonValue,
cdxIconPlay
};
}
} );
</script>
Vue usage
The v-model
value will be a boolean, it is true
if the button is currently toggled ("on") and false
otherwise ("off").
Props
Prop name | Description | Type | Default |
---|---|---|---|
modelValue | Whether the button should be set to "on" (true) or "off" (false). Provided by v-model binding in the parent component. | boolean | false |
disabled | Whether the disabled attribute should be added to the button, which prevents it from being clicked. | boolean | false |
quiet | Whether the toggle button should be "quiet", which renders more minimally. | boolean | false |
Events
Event name | Properties | Description |
---|---|---|
update:modelValue | modelValue boolean - The new model value | Emitted when modelValue changes (i.e. when the state is toggled) |
Slots
Name | Description | Bindings |
---|---|---|
default | Button content |