Buttons

The v-btn component replaces the standard html button with a material design theme and a multitude of options. Any color helper class can be used to alter the background or text color.

Usage

Buttons in their simplest form contain uppercase text, a slight elevation, hover effect, and a ripple effect on click.

API

Anatomy

The recommended placement of elements inside of v-btn is:

• Place text in the center
• Place visual content around container text

Guide

The v-btn component is commonly used throughout Vuetify and is a staple for any application. It is used for everything from navigation to form submission; and can be styled in a multitude of ways.

The following code snippet is an example of a basic v-btn component only containing text:

<v-btn>Button</v-btn>

Props

A wide array of props can be employed to modify the v-btn component's look and functionality. Props like prepend-icon and append-icon offer a straightforward approach to incorporate positioned icons, whereas block and stacked props are utilized to manage the component's form.

Density

The density prop is used to control the vertical space that the button takes up.

Size

The size property is used to control the size of the button and scales with density. The default size is undefined which essentially translates to medium.

Block

Block buttons extend the full available width of their container. This is useful for creating buttons that span the full width of a card or dialog.

::: info Block applies width: 100% which can cause overflow issues inside a flex container. :::

Rounded

Use the rounded prop to control the border radius of a button.

Elevation

The elevation property provides up to 24 levels of shadow depth. By default, buttons rest at 2dp.

Ripple

The ripple property determines whether the v-ripple directive is used.

Variants

The variant prop gives you easy access to several different button styles. Available variants are: elevated(default), flat, tonal, outlined, text, and plain.

Icon

Icons can be used for the primary content of a button. They are commonly used in the v-toolbar and v-app-bar components.

Loaders

Using the loading prop, you can notify a user that there is processing taking place. The default behavior is to use a v-progress-circular component but this can be customized with the loader slot.

Inside of bars

A common use-case is to use the v-btn with the icon property within a v-toolbar or v-app-bar component.

Slots

The v-btn component provides slots that enable you to customize content created by its props or to add additional content.

Slots give you greater control to customize the content of the v-btn component while still taking advantage of the easy-to-use props.

Icon color

When you use the prepend-icon and append-icon props in conjunction with the corresponding slot, prepend or append, you are able to place a v-icon that automatically injects the designated icon.

Spaced

By default icons stick to the button content, but you can space them out with spaced prop.

Custom loader

The loader slot allows you to customize the loading indicator. In this example we use a v-progress-linear component to create a loading bar that spans the full width of the button.

Examples

The following are a collection of examples that demonstrate more advanced and real world use of the v-btn component.

Discord event

In this example we utilize multiple different button variants and styles to create a copy of the Discord event card.

Survey group

In addition to Button groups, the v-btn component cant hook into a v-item-group using a special symbol. In the next example we create a group of buttons that are used to select a survey answer and add custom active state styling.

Tax form confirmation

This example utilizes the v-text-field component to collect data from the user and the loading prop of v-btn when submitting the form.

Dialog action

Buttons are often used to trigger actions within a v-dialog. In this example we use the outlined variant and the color prop to create a button that is visually distinct from the other buttons.

Cookie settings

In this example we use a v-banner component to display a custom cookie consent banner. Clicking the "Manage Cookies" button will prompt a v-dialog component.

Readonly buttons

In this example, we change the properties of the v-btn based upon a "subscription" state. When the user is subscribed, we want to disable interaction with the button, but not change its appearance; which is what occurs when using the disabled property.

Global Configuration

Modify the default values and set a default style for all v-btn components using the Global configuration. This helps keep your application consistent and allows you to change it in the future with minimal effort.

import { createVuetify } from 'vuetifyjs'

export default createVuetify({
  defaults: {
    VBtn: {
      color: 'primary',
      variant: 'outlined',
      rounded: true,
    },
  },
})

Aliasing

Utilize the component aliasing feature to generate virtual components derived from the v-btn component. This proves valuable when dealing with numerous button variations within design specifications or when developing a custom library based on Vuetify.

import { createVuetify } from 'vuetifyjs'
import { VBtn } from 'vuetifyjs/components'

export createVuetify({
  aliases: {
    VBtnSecondary: VBtn,
    VBtnTertiary: VBtn,
  },
  defaults: {
    VBtn: {
      color: 'primary',
      variant: 'text',
    },
    VBtnSecondary: {
      color: 'secondary',
      variant: 'flat',
    },
    VBtnTertiary: {
      rounded: true,
      variant: 'plain',
    },
  },
})

SASS Variables

Make fine tuned changes by modifying the v-btn SASS variables. This is useful when you want to change the default button height or padding.

@use 'vuetify/settings' with (
  $button-banner-actions-padding: 16px,
  $button-height: 32px,
);

Some of these values can be modified using the Global configuration as well and will take precedence over the SASS variables. For example, the height prop can be used to change the default button height without modifying the SASS variables.

Defaults Side Effects

There are instances where a set of default properties are injected or custom styling is applied to the v-btn. This can be for a variety of reasons, but the most common are:

• to match a design specification
• to provide a better visual appearance based upon context
• to avoid creating proprietary components; e.g. v-bottom-navigation-btn and v-card-btn

Banners

The v-banner-actions component applies the text variant and slim prop, reducing button x-axis padding to 8px.

The following properties are modified when used within a v-banner-actions component:

Bottom navigation

The v-bottom-navigation component scopes out all previously provided defaults and applies its own. This is to avoid changes made to v-btn in the Global configuration. Buttons automatically register with v-bottom-navigation's' group and will update the model when clicked.

The following properties are modified when used within a v-bottom-navigation component:

Button groups

The v-btn-group component makes multiple changes to the v-btn component.

The following properties are modified when used within a v-btn-group component:

Cards

The v-card-actions component applies the text variant and slim prop, reducing button x-axis padding to 8px, and applies a start margin for all siblings. This is to ensure the text from the button lines up with the text and title of the card and that there is space between its actions.

The following properties are modified when used within a v-card-actions component:

Snackbars

The v-snackbar component applies the text variant, slim prop, and removes ripples from all v-btn components.

The following properties are modified when used within the actions slot of the v-snackbar component:

Toolbars and AppBars

The v-toolbar component applies the text variant to all v-btn components. In addition, the v-toolbar-items component is used to create a grouping of buttons that fill the height of the toolbar.

::: info

The v-app-bar component uses v-toolbar internally. When applying global defaults, you must target the v-toolbar component.

:::

export default createVuetify({
  defaults: {
    VToolbar: {
      VBtn: { variant: 'flat' },
    },
  },
})

The following properties are modified when used within a v-toolbar or v-toolbar-items component:

Accessibility

The v-btn component is an extension of the native button element and supports all of the same accessibility features.

ARIA Attributes

By default, the v-btn component includes relevant WAI-ARIA attributes to enhance accessibility. The component is automatically assigned the type="button" attribute, which indicates its purpose as a button to assistive technologies.

Keyboard Navigation

The v-btn component is natively focusable and responds to keyboard events, such as pressing the <v-kbd>Enter</v-kbd> or <v-kbd>Space</v-kbd> key to trigger the button's action. This ensures that users can navigate and interact with your application using just the keyboard.

Accessible Labels

When using a v-icon within the v-btn component (e.g., with the icon prop), it is essential to provide a text alternative for screen reader users. You can add an aria-label attribute with a descriptive label to ensure that the button's purpose is clear to all users.

<v-btn
  aria-label="Refresh"
  icon="mdi-refresh"
></v-btn>

Touch Target Size

Make sure your buttons have an adequate touch target size, especially on touch devices. A larger touch target can improve the usability of your buttons for users with motor impairments or those using small screens. You can use large or x-large values for the size prop to increase the button size:

<v-btn size="large">
  Large Button
</v-btn>

<v-btn size="x-large">
  Extra Large Button
</v-btn>