#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
| Component | Description |
|---|---|
| v-btn | Primary Component |
#Anatomy
The recommended placement of elements inside of v-btn is:
- Place text in the center
- Place visual content around container text
| Element / Area | Description |
|---|---|
| 1. Container | In addition to text, the Button container typically holds a v-icon component |
| 2. Icon (optional) | Leading media content intended to improve visual context |
| 3. Text | A 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-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.
| Value | Example | Description |
|---|---|---|
| elevated | Elevates the button with a shadow | |
| flat | Removes button shadow | |
| tonal | Background color is a lowered opacity of the current text color | |
| outlined | Applies a thin border with the current text color | |
| text | Removes the background and removes shadow | |
| plain | Removes the background and lowers the opacity until hovered |
The block applies width: 100% which can have overflow issues when inside of a flex container.
#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.
| Slot | Description |
|---|---|
| 1. Default | The default slot |
| 2. Prepend | Content area before the default slot |
| 3. Append | Content area after the default slot |
| 4. Loader | Content 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-icon that 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-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 comfirmation
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.
#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-btnandv-card-btn
#Banners
The v-banner-actions component applies the text variant and reduces button x-axis padding to 8px.
| Documentation | API |
|---|---|
| Banners | v-banner-actions |
The following properties are modified when used within a v-banner-actions component:
| Property | Value |
|---|---|
| color | provided by v-banner-actions |
| density | provided by v-banner-actions |
| variant | text |
#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.
| Documentation | API |
|---|---|
| Bottom navigation | v-bottom-navigation |
The following properties are modified when used within a v-bottom-navigation component:
| Property | Value |
|---|---|
| color | provided by v-bottom-navigation |
| density | provided by v-bottom-navigation |
| stacked | true when mode is shift |
| variant | text |
#Button groups
The v-btn-group component makes multiple changes to the v-btn component.
| Documentation | API |
|---|---|
| Button groups | v-btn-group |
The following properties are modified when used within a v-btn-group component:
| Property | Value |
|---|---|
| color | provided by v-btn-group |
| height | auto |
| density | provided by v-btn-group |
| flat | true |
| variant | provided 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.
| Documentation | API |
|---|---|
| Cards | v-card-actions |
The following properties are modified when used within a v-card-actions component:
| Property | Value |
|---|---|
| variant | text |
#Snackbars
The v-snackbar component applies the text variant and removes ripples from all v-btn components.
| Documentation | API |
|---|---|
| Snackbars | v-snackbar |
The following properties are modified when used within the actions slot of the v-snackbar component:
| Property | Value |
|---|---|
| ripple | false |
| variant | text |
#Toolbars
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.
The following properties are modified when used within a v-toolbar or v-toolbar-items component:
| Property | Value |
|---|---|
| height | provided by v-toolbar-items |
| variant | text |
#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 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
#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>