```ts
import Button from "~/components/ui/Button.vue"
```
# Button
Buttons are UI elements that users can interact with to perform actions and manipulate objects. They are distinct from [Links](link) and will not change the user's position.
```ts
{
thinFont?: true
lowHeight?: true
isActive?: boolean
isLoading?: boolean
shadow?: boolean
round?: boolean
icon?: string
onClick?: (...args: any[]) => void | Promise
autofocus?: boolean
ariaPressed?: true
} & (ColorProps | DefaultProps)
& VariantProps
& RaisedProps
& WidthProps
& AlignmentProps
```
## Action
[The default action of buttons is `submit` \[mdn\]](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#type). Specify an [`onClick` or `@click`](#short-form-click) function to change the behavior of a button.
```vue-html
```
### Short-form @click
For convenience, you can use the Vue-specific `@click` syntax to add the `onClick` prop. The following two buttons are effectively equal:
```vue-html
```
## Button colors
Buttons come in different types depending on the type of action they represent.
Find [a complete overview of recommended styles on the color page](../../using-color#links-and-buttons).
### Default
Default buttons represent **neutral** actions such as cancelling a change or dismissing a notification.
```vue-html
```
### Primary
The primary button represents the **single positive** action on a page or modal, such as uploading, confirming, and accepting changes.
```vue-html
```
### Secondary
Secondary buttons represent **neutral** actions such as cancelling a change or dismissing a notification.
```vue-html
```
Note that on a secondary background, the button needs to be `raised` to make it stand out.
### Destructive
Desctrutive buttons represent **dangerous** actions including deleting items or purging domain information.
```vue-html
```
## Button variants
Buttons come in different styles that you can use depending on the location of the button.
### Solid
Solid buttons have a filled background. Use these to emphasize the action the button performs.
::: info
This is the default style. If you don't specify a style, a solid button is rendered.
:::
```vue-html
```
### Outline
Outline buttons have a transparent background. Use these to deemphasize the action the button performs.
```vue-html
```
### Ghost
Ghost buttons have a transparent background and border. Use these to deemphasize the action the button performs.
```vue-html
```
## Button styles
### Shadow
You can give a button a shadow to add depth.
```vue-html
```
## Button shapes
You can choose different shapes for buttons depending on their location and use.
### Normal
Normal buttons are slightly rounded rectangles.
::: info
This is the default shape. If you don't specify a type, a normal button is rendered.
:::
```vue-html
```
### Round
Round buttons have fully rounded edges.
```vue-html
```
## Split button
## Button states
### On/Off
You can force an active state by passing an `aria-pressed` prop.
::: tip When do I use a Toggle vs. a Button?
**Use a Button with an `aria-pressed` prop**
- if the semantics of the option change depending whether it's on or off
- to perform asynchronous, stateful and fallible actions
**Examples:**
- Toggle a remote property
- Open/close a section in the UI
- Toolbar buttons that toggle through many options such as "Paragraph/Heading/List"
**Use the [ToggleΒ component](toggle) (a.k.a. switch)**
- for options that don't cause side-effects and never change the Toggle label content based on the Toggle state (think of the traditional checkbox).
- for options that don't have any intermediary state besides "on" and "off"
**Examples:**
- A checkbox in the User settings
- A checkbox in a form that the user submits later
:::
```vue-html
```
**Default:**
---
**Secondary:**
---
**Primary:**
### Disabled
Disabled buttons are non-interactive and inherit a less bold color than the one provided.
::: tip When do I use `disabled`?
Use the `disabled` property for buttons that the user expects at a certain position, for example in a toolbar or in a row of action buttons.
If there is just one button in a form and its action is disabled, you may instead just remove it.
:::
```vue-html
```
### Loading
If a user can't interact with a button until something has finished loading, you can add a spinner by passing the `is-loading` prop.
```vue-html
```
### Promise handling in `@click`
When a function passed to `@click` returns a promise, the button automatically toggles a loading state on click. When the promise resolves or is rejected, the loading state turns off.
::: danger
There is no promise rejection mechanism implemented in the `