Skip to content

Latest commit

 

History

History
1302 lines (1168 loc) · 38.5 KB

button.md

File metadata and controls

1302 lines (1168 loc) · 38.5 KB
title description status thumb image storybook figma_url keywords
Button
A button is an UI element which signals key actions to take an action throughout an app. It is important a button is identifiable, consistent, communicates its actions clearly, and is appropriately sized to its action.
ready
true
assets/images/components/button.png
btn
click
action
cta
d-button
DtButton
dt-button
Place Call

Usage

  • <button> and link (<a>) HTML elements each describe a specific intent. Understanding the distinction is important: if it goes somewhere, it's a link (<a>). If an action occurs, use a Button (<button>). When you need button styling with navigation behavior (CTAs, toolbar actions that navigate), use DtButton's href or to props — see Navigation.
  • Avoid using too many buttons on a page.
  • Set the type attribute to define its purpose: submit, button, or reset. Browsers default to submit if it isn't defined, and that cannot be assumed as the preferred behavior.
  • Conveying that an action that will occur when invoked.
  • To trigger an action or behavior, such as submitting a form or spawning a Modal.
  • Avoid using to navigate between destinations, deferring to a Link instead. Exception: use DtButton with href or to when button styling is intentional (e.g. CTAs, toolbar actions).

Writing Guidelines

Button labels should be clear and predictable so users have confidence in their actions.

  • Lead with a strong verb and use verb + noun structure except for common actions like “Done,” “Close,” “Cancel,” or “OK”
  • Should be sentence case
  • Do not use punctuation
  • Avoid unnecessary articles such as “the,” “an,” and “a.”
  • Add number
  • Create menu
  • Add Number
  • Create a menu

Variants

Dialtone provides five options for kind, with three levels of importance.

Default

The base button should be the go-to button for most of your needs. When in doubt, use this style. To help provide clarity to users, it is generally recommended to use only one primary button style within a section or page.

Place Call Place Call Place Call

Danger

The danger button style is used to communicate critical or destructive actions such as deleting content, accounts, or canceling services.

Place Call Place Call Place Call

Positive

The positive button style is used to communicate positive actions.

Place Call Place Call Place Call

Muted

The muted button style is used to communicate non-primary actions for contexts in which the base style may not work (e.g. colored backgrounds, validation components, etc). This style’s use should be rare. When in doubt, use the default button style.

Place Call Place Call

Disabled

Disabled Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call

Buttons can be disabled using the disabled attribute or the Dialtone class, d-btn--disabled. Use the attribute when a button should appear disabled and not receive focus; use the class when a button should appear disabled but still receive focus (i.e. a disabled button with a tooltip).

Using the class also requires aria-disabled, and additional javascript implementation is required to prevent events.

Place Call (disabled attribute) Place Call (disabled class)

<code-example-tabs :htmlCode='() => $refs.disabledExample' vueCode='

Place Call

Place Call (disabled class) ' showHtmlWarning />

Active

Buttons can be set to active state using the active prop or .d-btn--active Dialtone class.

Place Call Place Call Place Call Place Call Place Call

Link

Buttons can be styled as a Link in situations for which you need the appearance of a link but behavior of a button. Using the button element provides a better accessibility experience.

Place Call Place Call Place Call Place Call Place Call Place Call

Link no underline

This inverts the underline behavior. With underline="false", the link will not have an underline by default, but will show one on hover.

Place Call Place Call

Unstyled

The unstyled button removes all default Dialtone styling while preserving the semantic HTML <button> element and maintaining proper button behavior and accessibility.

Place Call

Inverted

<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16"

kind="inverted" has been deprecated. Use the v-dt-mode directive instead, or DtModeIsland.

Use the v-dt-mode directive in place of kind="inverted" on the component element. The previous inverted variant of DtButton was limited to a single presentation style. The directive now makes every combination available as an inverted style.

Inverted Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call Place Call

Navigation

DtButton can render as an <a> or <router-link> for cases where you need button styling with navigation behavior.

  • Navigating within the app? Use to. Renders <router-link> for client-side navigation without page reloads.
  • Linking to an external site? Use href. Renders <a> for standard browser navigation.
  • Triggering an action? Use neither. Renders <button> (default).

href

Pass href to render as an <a> element. Use target="_blank" and rel="noopener noreferrer" for external links.

Dialtone

<code-example-tabs :htmlCode='() => $refs.hrefExample1' vueCode=' <dt-button href="https://dialtone.dialpad.com" target="_blank" rel="noopener noreferrer" kind="muted" importance="outlined" size="sm" icon-position="right"

<template #icon="{ iconSize }"> Dialtone ' showHtmlWarning />

to

Pass to to render as <router-link> for internal client-side SPA navigation. Use replace to navigate without adding a history entry.

Home

Migration

If you have existing <a class="d-btn"> or <router-link class="d-btn"> workarounds, replace them with DtButton props:

<code-example-tabs vueCode='

<a class="d-btn d-btn--primary d-btn--outlined d-btn--sm" href="https://example.com" target="_blank" rel="noopener noreferrer"

Link Text

<dt-button href="https://example.com" target="_blank" rel="noopener noreferrer" importance="outlined" size="sm"

Link Text ' />

<code-example-tabs vueCode='

<router-link class="d-btn d-btn--primary d-btn--sm" :to="roomPath"

Join Room

Join Room ' />

Sizes

The default button size is md, but does not need to be explicitly specified.

Place Call Place Call Place Call Place Call Place Call

Icon Support

<dt-notice kind="info" class="d-wmx100p d-my24" hide-close title="Note"

startIcon and endIcon slots replace the previous icon slot and icon-position prop, which are deprecated and will be sunset.

Start and End

Place icons before and/or after inline of the label with startIcon and endIcon slots.

Label Label Label

Top and Bottom

Place icons above or below the label with blockStartIcon and blockEndIcon slots.

Label Label

Icon Only

Icon-only buttons are commonly used for toggling actions, navigation, or closing UI elements.

Circle

The following styles are available as a circle shape.

Loading

Loading buttons are useful for communicating a delay between the button interaction and its action taking place. Every button style can accept the loading button class, though we only provide a few possible examples.

Replace button label

The width of the button remains determined by the length of the label, which is visually hidden in this state.

Place Call Place Call

With label

Validating Validating Validating Validating

Leading & Trailing

Use the #leading and #trailing slots to render freeform content at the start or end of a button — outside the label area but inside the button's border. Common use cases include badges, count indicators, or keyboard shortcut hints. Use leading-class and trailing-class to add padding or styling to the slot containers.

<dt-notice kind="info" title="Info"

This is not to be confused with #icon slots, which are specifically for icons. leading and trailing are essentially freeform.

Leading

Caution

Trailing

Copy

Split Button

<dt-notice kind="info" class="d-wmx100p d-my16"

DtSplitButton is its own component containing multiple DtButtons.

Place call Option 1 Option 2 Option 3

Branded

We provide the following branded buttons for log-in and sign-up workflows.

Log in with Google Log in with Office365 Log in with LinkedIn 
<button class="d-btn d-btn--brand d-btn--google" type="button">
  <span class="d-btn__icon"><icon-google-glyph /></span>
  <span class="d-btn__label">Log in with Google</span>
</button>
<button class="d-btn d-btn--brand d-btn--o365" type="button">
  <span class="d-btn__icon"><icon-google-glyph /></span>
  <span class="d-btn__label">Log in with Office365</span>
</button>
<button class="d-btn d-btn--brand d-btn--linkedin" type="button">
  <span class="d-btn__icon"><icon-google-glyph /></span>
  <span class="d-btn__label">Log in with LinkedIn</span>
</button>

Vue API

Accessibility

  • Choosing between Link and Button elements is paramount for screenreaders to inform the user what will occur. For example: will it go somewhere (Link) or will something happen (Button)?
  • Do not rely on color alone to convey the intent of the button. Defer to the button text as primary way to convey the buttons intent.
  • Display a visible focus state when users tab to them.
  • Use standard semantic usage of HTML elements.
  • Be aware of how screenreaders handle buttons and links differently. For example, both the Enter and Space keys triggers a button, while links are triggered only by the Enter key.
  • If it is a button type while focused:
    • Pressing the Enter or Space key should trigger the action.
    • Pressing the Tab key moves focus to the next focusable element.
    • Pressing the Shift+Tab key moves focus to the previous focusable element.
  • When using DtButton with href or to, the component automatically handles Spacebar activation and disabled state (aria-disabled, tabindex="-1"). Navigating elements keep their native link role — role="button" is not added because the element navigates rather than performing an in-page action.

Classes

<script setup> import { ref } from 'vue'; import ButtonVariantsTable from '@baseComponents/ButtonVariantsTable.vue'; const isDisabled = ref(true); const isInverted = ref(true); </script>