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

ComponentDescription
v-btnPrimary Component

Anatomy

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

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

Element / AreaDescription
1. ContainerIn addition to text, the Button container typically holds a v-iconcomponent
2. Icon (optional)Leading media content intended to improve visual context
3. TextA content area for displaying text and other inline elements

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.

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-rippledirective 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.

ValueExampleDescription
elevatedElevates the button with a shadow
flatRemoves button shadow
tonalBackground color is a lowered opacity of the current text color
outlinedApplies a thin border with the current text color
textRemoves the background and removes shadow
plainRemoves the background and lowers the opacity until hovered

Icon

Icons can be used for the primary content of a button. They are commonly used in the v-toolbarand v-app-barcomponents.

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-toolbaror v-app-barcomponent.

Slots

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

SlotDescription
1. DefaultThe default slot
2. PrependContent area before the default slot
3. AppendContent area after the default slot
4. LoaderContent area shown when loading is set to true

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-iconthat automatically injects the designated icon.

Custom loader

The loader slot allows you to customize the loading indicator. In this example we use a v-progress-linearcomponent 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-groupusing 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 comfirmation

This example utilizes the v-text-fieldcomponent 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.

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.

src/plugins/vuetify.js
import { createVuetify } from 'vuetifyjs'

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

Aliasing

Utilize the component aliasingfeature 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.

src/plugins/vuetify.js
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.

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

Some of these values can be modified using the Global configurationas 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 reduces button x-axis padding to 8px.

DocumentationAPI
Bannersv-banner-actions

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

PropertyValue
colorprovided by v-banner-actions
densityprovided by v-banner-actions
varianttext

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:

PropertyValue
colorprovided by v-bottom-navigation
densityprovided by v-bottom-navigation
stackedtrue when mode is shift
varianttext

Button groups

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

DocumentationAPI
Button groupsv-btn-group

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

PropertyValue
colorprovided by v-btn-group
heightauto
densityprovided by v-btn-group
flattrue
variantprovided by v-btn-group

Cards

The v-card-actions component applies the text variant, reduces 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.

DocumentationAPI
Cardsv-card-actions

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

PropertyValue
varianttext

Snackbars

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

DocumentationAPI
Snackbarsv-snackbar

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

PropertyValue
ripplefalse
varianttext

Toolbars

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

DocumentationAPI
Toolbarsv-toolbar

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

PropertyValue
heightprovided by v-toolbar-items
varianttext

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-ARIAattributes to enhance accessibility. The component is automatically assigned the role="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

Enter
or
Space
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-iconwithin 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>

Ready for more?

Continue your learning with related content selected by the Team or move between pages by using the navigation links below.
Edit this page onGitHub