CodexToggleButton
A button that can be toggled on and off.
You should always include some content to display on the button via the default slot.
The v-model value will be a boolean, it is true if the button is currently toggled ("on") and false otherwise (button is "off").
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
vue
<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>vue
<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.
vue
<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>vue
<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>Usage
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 |