Button

Buttons trigger an action, such as submitting a form, closing a dialog, or navigating to a new page.

Usage

import { registerButton } from '@vonage/vivid-api';

registerButton('your-prefix');

Link Buttons

Use the href attribute to change the button to a link. When doing so, all of the native attributes of <a> are supported, including target.

Semantically, buttons are usually used for triggering actions, while links are used for navigation. Mixing these semantics might lead to confusion or unexpected behavior for users.

<script setup lang="ts">
import { VButton, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VButton label="Button as a link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a" target="_blank" icon-trailing appearance="filled" connotation="cta">
    <template #icon><VIcon name="chevron-right-line" /></template>
  </VButton>
</template>

<vwc-button label="Button as a link" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a" target="_blank" icon-trailing appearance="filled" connotation="cta">
  <vwc-icon slot="icon" name="chevron-right-line"></vwc-icon>
</vwc-button>

See Client-Side Navigation for more information on how to integrate with Vue Router.

Slots

Icon Slot

Use the icon slot to customise icons. If set, the icon attribute is ignored.

<script setup lang="ts">
import { VButton, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VButton aria-label="Mute" appearance="outlined">
    <template #icon
      ><VIcon>
        <svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
          <g>
            <path d="M5.5 9.6C5.5 13.1344 8.41037 16 12 16C15.5896 16 18.5 13.1344 18.5 9.6V6.4C18.5 2.8656 15.5896 0 12 0C8.41037 0 5.5 2.8656 5.5 6.4V9.6Z" fill="var(--vvd-color-success-400)" />
            <path d="M5.5 9.6C5.5 13.1344 8.41037 16 12 16C15.5896 16 18.5 13.1344 18.5 9.6V6.4C18.5 2.8656 15.5896 0 12 0C8.41037 0 5.5 2.8656 5.5 6.4V9.6Z" fill="currentColor" id="animation" class="color-animation" />
            <path d="M3 10.3333C3 9.59695 2.32843 9 1.5 9C0.671573 9 0 9.59695 0 10.3333C0 15.7728 4.58052 20.2613 10.5 20.9175V24H13.5V20.9175C19.4195 20.2613 24 15.7728 24 10.3333C24 9.59695 23.3284 9 22.5 9C21.6716 9 21 9.59695 21 10.3333C21 14.7516 16.9706 18.3333 12 18.3333C7.02943 18.3333 3 14.7516 3 10.3333Z" fill="currentColor" />
          </g>
        </svg>
      </VIcon>
    </template>
  </VButton>
</template>

<style>
.color-animation {
  animation: heightChange 1.5s infinite;
}
@keyframes heightChange {
  0% {
    clip-path: inset(0% 0% 0% 0%);
  }
  25% {
    clip-path: inset(0% 0% 45% 0%);
  }
  50% {
    clip-path: inset(0% 0% 80% 0%);
  }
  100% {
    clip-path: inset(0% 0% 0% 0%);
  }
}
</style>

<vwc-button aria-label="Mute" appearance="outlined">
  <vwc-icon slot="icon">
    <svg width="24" height="24" viewBox="0 0 24 24" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
      <g>
        <path d="M5.5 9.6C5.5 13.1344 8.41037 16 12 16C15.5896 16 18.5 13.1344 18.5 9.6V6.4C18.5 2.8656 15.5896 0 12 0C8.41037 0 5.5 2.8656 5.5 6.4V9.6Z" fill="var(--vvd-color-success-400)" />
        <path d="M5.5 9.6C5.5 13.1344 8.41037 16 12 16C15.5896 16 18.5 13.1344 18.5 9.6V6.4C18.5 2.8656 15.5896 0 12 0C8.41037 0 5.5 2.8656 5.5 6.4V9.6Z" fill="currentColor" id="animation" class="color-animation" />
        <path d="M3 10.3333C3 9.59695 2.32843 9 1.5 9C0.671573 9 0 9.59695 0 10.3333C0 15.7728 4.58052 20.2613 10.5 20.9175V24H13.5V20.9175C19.4195 20.2613 24 15.7728 24 10.3333C24 9.59695 23.3284 9 22.5 9C21.6716 9 21 9.59695 21 10.3333C21 14.7516 16.9706 18.3333 12 18.3333C7.02943 18.3333 3 14.7516 3 10.3333Z" fill="currentColor" />
      </g>
    </svg>
  </vwc-icon>
</vwc-button>

<style>
  .color-animation {
    animation: heightChange 1.5s infinite;
  }
  @keyframes heightChange {
    0% {
      clip-path: inset(0% 0% 0% 0%);
    }
    25% {
      clip-path: inset(0% 0% 45% 0%);
    }
    50% {
      clip-path: inset(0% 0% 80% 0%);
    }
    100% {
      clip-path: inset(0% 0% 0% 0%);
    }
  }
</style>

CSS Variables

Button Content Alignment

When dropdown-indicator is set button, the content alignment is set to start.
If center is needed, set --button-content-alignment: center;.

<script setup lang="ts">
import { VButton } from '@vonage/vivid-api-vue';
</script>

<template>
  <div class="container">
    <VButton class="button" dropdown-indicator appearance="outlined-light" label="Aligned to start content" />
    <VButton class="button button-center" dropdown-indicator appearance="outlined-light" label="Centered content" />
  </div>
</template>

<style>
.container {
  display: flex;
  gap: 4px;
}
.button {
  inline-size: 300px;
}
.button-center {
  --button-content-alignment: center;
}
</style>

<div class="container">
  <vwc-button class="button" dropdown-indicator appearance="outlined-light" label="Aligned to start content"></vwc-button>
  <vwc-button class="button button-center" dropdown-indicator appearance="outlined-light" label="Centered content"></vwc-button>
</div>

<style>
  .container {
    display: flex;
    gap: 4px;
  }
  .button {
    inline-size: 300px;
  }
  .button-center {
    --button-content-alignment: center;
  }
</style>

API Reference

Properties

Property	Type	Description
active	`boolean`	Displays the button in active state.
appearance	`'ghost' \| 'filled' \| 'outlined' \| 'ghost-light' \| 'outlined-light'`	The appearance the button should have.
autofocus	`boolean`	Determines if the element should receive document focus on page load.
connotation	`'alert' \| 'accent' \| 'cta' \| 'success' \| 'announcement'`	The connotation the button should have.
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
download	`string`	Prompts the user to save the linked URL. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
dropdownIndicator	`boolean`	Display a chevron to indicate that the button opens a dropdown.
formId	`string`	The id of a form to associate the element to.
formaction	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formenctype	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formmethod	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formnovalidate	`boolean`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formtarget	`'_self' \| '_blank' \| '_parent' \| '_top'`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
href	`string`	The URL the hyperlink references. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
hreflang	`string`	Hints at the language of the referenced resource. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
iconTrailing	`boolean`	Indicates the icon affix alignment.
initialValue	`string`	The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
label	`string`	Indicates the button's label.
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
pending	`boolean`	Displays the button in pending state.
ping	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
pressed	`boolean`	Indicates the button is in a pressed/toggled state. Sets `aria-pressed` on the button element.
referrerpolicy	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
rel	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
required	`boolean`	Require the field to be completed prior to form submission.
shape	`'rounded' \| 'pill'`	The shape the button should have.
size	`'condensed' \| 'normal' \| 'expanded' \| 'super-condensed'`	The size the button should have.
stacked	`boolean`	Indicates the icon is stacked.
target	`'_self' \| '_blank' \| '_parent' \| '_top'`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
title	`string`	Specifies extra information about the button. This information is typically used by browsers to display a tooltip.
type	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
value	`string`	The current value of the element.

Property	Type	Description
active	`boolean`	Displays the button in active state.
appearance	`'ghost' \| 'filled' \| 'outlined' \| 'ghost-light' \| 'outlined-light'`	The appearance the button should have.
autofocus	`boolean`	Determines if the element should receive document focus on page load.
connotation	`'alert' \| 'accent' \| 'cta' \| 'success' \| 'announcement'`	The connotation the button should have.
disabled	`boolean`	Sets the element's disabled state. A disabled element will not be included during form submission.
download	`string`	Prompts the user to save the linked URL. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
dropdown-indicator	`boolean`	Display a chevron to indicate that the button opens a dropdown.
form	`string`	The id of a form to associate the element to.
formaction	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formenctype	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formmethod	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formnovalidate	`boolean`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
formtarget	`'_self' \| '_blank' \| '_parent' \| '_top'`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button \| <button> element for more details.
href	`string`	The URL the hyperlink references. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
hreflang	`string`	Hints at the language of the referenced resource. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
icon-trailing	`boolean`	Indicates the icon affix alignment.
value	`string`	The default value of the element. This value sets the `value` property only when the `value` property has not been explicitly set.
label	`string`	Indicates the button's label.
name	`string`	The name of the element. This element's value will be surfaced during form submission under the provided name.
pending	`boolean`	Displays the button in pending state.
ping	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
pressed	`boolean`	Indicates the button is in a pressed/toggled state. Sets `aria-pressed` on the button element.
referrerpolicy	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
rel	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
required	`boolean`	Require the field to be completed prior to form submission.
shape	`'rounded' \| 'pill'`	The shape the button should have.
size	`'condensed' \| 'normal' \| 'expanded' \| 'super-condensed'`	The size the button should have.
stacked	`boolean`	Indicates the icon is stacked.
target	`'_self' \| '_blank' \| '_parent' \| '_top'`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
title	`string`	Specifies extra information about the button. This information is typically used by browsers to display a tooltip.
type	`string`	See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a \| <a> element for more information.
current-value	`string`	The current value of the element.

Slots

Name	Description
icon	The preferred way to add an icon to the component.

Name	Description
icon	The preferred way to add an icon to the component.

Methods

Name	Returns	Description
checkValidity	`boolean`	Return the current validity of the element.
reportValidity	`boolean`	Return the current validity of the element. If false, fires an invalid event at the element.
validate	`void`	{@inheritDoc (FormAssociated:interface).validate}