ToggleButton
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
Toggle the ToggleButton to see the value change. Open up the console to see emitted events.
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"
>
Button label
</cdx-toggle-button>
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButton } from '@wikimedia/codex';
import getEventLogger from '../../../src/utils/getEventLogger';
export default defineComponent( {
name: 'SingleButton',
components: { CdxToggleButton },
setup() {
const buttonValue = ref( false );
const onUpdate = getEventLogger<boolean>( 'update:modelValue' );
return {
buttonValue,
onUpdate
};
}
} );
</script>
Stateful
Example usage as a pause/play button, changing the icon and text when toggled.
vue
<template>
<div>
<cdx-toggle-button
v-model="buttonValue"
>
<cdx-icon :icon="buttonIcon" />
{{ buttonText }}
</cdx-toggle-button>
</div>
</template>
<script lang="ts">
import { computed, defineComponent, ref } from 'vue';
import { CdxToggleButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconPause, cdxIconPlay, Icon } from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'IconButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
// Pause/play menu - button not active means currently paused
const buttonIcon = computed( (): Icon => {
if ( buttonValue.value ) {
// Currently playing
return cdxIconPause;
}
return cdxIconPlay;
} );
const buttonText = computed( (): string => {
if ( buttonValue.value ) {
// Currently playing
return 'Pause';
}
return 'Play';
} );
return {
buttonValue,
buttonIcon,
buttonText
};
}
} );
</script>
Stateful (icon-only)
Example usage as an icon-only pause/play button, changing the icon when toggled.
vue
<template>
<div>
<cdx-toggle-button
v-model="buttonValue"
>
<cdx-icon :icon="buttonIcon" :icon-label="iconLabel" />
</cdx-toggle-button>
</div>
</template>
<script lang="ts">
import { computed, defineComponent, ref } from 'vue';
import { CdxToggleButton, CdxIcon } from '@wikimedia/codex';
import { cdxIconPause, cdxIconPlay, Icon } from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'IconOnlyButton',
components: { CdxToggleButton, CdxIcon },
setup() {
const buttonValue = ref( false );
// Pause/play menu - button not toggled on means currently paused.
const buttonIcon = computed( (): Icon => {
if ( buttonValue.value ) {
// Currently playing.
return cdxIconPause;
}
return cdxIconPlay;
} );
const iconLabel = computed( (): string => {
if ( buttonValue.value ) {
// Currently playing
return 'Pause';
}
return 'Play';
} );
return {
buttonValue,
buttonIcon,
iconLabel
};
}
} );
</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 |