import Button from "@ui/Button.vue"

Button ​

Buttons are UI elements that users can interact with to perform actions and manipulate objects. They are distinct from Links and will not change the user's position.

{
  thinFont?: true
  lowHeight?: true

  isActive?: boolean
  isLoading?: boolean

  shadow?: boolean
  round?: boolean
  icon?: string

  onClick?: (...args: any[]) => void | Promise<void>

  autofocus?: boolean
  ariaPressed?: true
} & (ColorProps | DefaultProps)
  & VariantProps
  & RaisedProps
  & WidthProps
  & AlignmentProps

Action ​

The default action of buttons is submit [mdn]. Specify an onClick or @click function to change the behavior of a button.

<form>
  <Button>Without `onClick`</Button>
  <Button :onClick="() => {}">With `onClick`</Button>
</form>

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:

  <Button :onClick="() => { console.log('Hi!') }"> Long form </Button>
  <Button @click="console.log('Hi!')"> Short form </Button>

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.

Default ​

Default buttons represent neutral actions such as cancelling a change or dismissing a notification.

<Button>
  Default button
</Button>

Primary ​

The primary button represents the single positive action on a page or modal, such as uploading, confirming, and accepting changes.

<Button primary>
  Primary button
</Button>

Secondary ​

Secondary buttons represent neutral actions such as cancelling a change or dismissing a notification.

<Button secondary raised>
  Secondary button
</Button>

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.

<Button destructive>
  Destructive button
</Button>

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.

<Button>
  Filled button
</Button>

<Button solid>
  Also filled button
</Button>

Outline ​

Outline buttons have a transparent background. Use these to deemphasize the action the button performs.

<Button outline secondary>
  Outline button
</Button>

Ghost ​

Ghost buttons have a transparent background and border. Use these to deemphasize the action the button performs.

<Button ghost secondary>
  Ghost button
</Button>

Button styles ​

Shadow ​

You can give a button a shadow to add depth.

<Button shadow>
  Shadow button
</Button>

Button shapes ​

You can choose different shapes for buttons depending on their location and use.

Normal ​

Normal buttons are slightly rounded rectangles.

<Button>
  Normal button
</Button>

Round ​

Round buttons have fully rounded edges.

<Button round>
  Round button
</Button>

Split button ​

Button states ​

On/Off ​

You can force an active state by passing an aria-pressed prop.

<Button>
  Off
</Button>

<Button aria-pressed>
  On
</Button>

Default:

Secondary:

Primary:

Disabled ​

Disabled buttons are non-interactive and inherit a less bold color than the one provided.

<Button disabled>
  Disabled button
</Button>

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.

<Button is-loading>
  Loading button
</Button>

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.

<script setup lang="ts">
const click = () => new Promise((resolve) => setTimeout(resolve, 1000));
</script>

<template>
  <Button @click="click"> Click me </Button>
</template>

You can override the promise state by passing a false is-loading prop.

<Button :is-loading="false">
  Click me
</Button>

Add an icon ​

You can use Bootstrap Icons in your button component.

<Button icon="bi-three-dots-vertical" />
<Button round icon="bi-x large" />
<Button primary icon="bi-save" button-width/>
<Button destructive icon="bi-trash">
  Delete
</Button>
<Button low-height icon="right bi-chevron-right">
  Next
</Button>

Add a badge ​

A badge strongly urges the user to take a destructive or maintenance action. Only use when all of the following criteria are met:

1. A maintenance problem calls for immediate action
2. The button or link is the fastest way to get there
3. The user needs to take a maintenance action to make the badge disappear

Typical example include:

• A message inboxes where the primary feature is reading and archiving messages (in Funkwhale: User messages)
• A moderation feature where reports need to be answered

You can also use badges to show result numbers, but more subtle affordances are preferable. Users expect to be able to eliminate the badge through maintenance action (criterion 3).

The default badge color is yellow. To differentiate priority levels or types of badges, you can use different colors. Note that many users cannot perceive the difference between certain colors, so don't use this feature for essential functionality. As of now, you can use any class name as the first word in the badge prop. Combine several classes with . (dot).

<span v-for="(color, index) in ['red', 'blue', 'green', 'violet', 'primary', 'secondary', 'secondary.raised']">
    <Button :badge="`${color} ${index}`">
        {{ color }}
    </Button>
</span>

Set width and alignment ​

See Using width and Using alignment

    <Button min-content>🐌</Button>
    <Button tiny>🐌</Button>
    <Button buttonWidth>🐌</Button>
    <Button small>🐌</Button>
    <Button auto>🐌</Button>
    <hr />
    <Button alignSelf="start">🐌</Button>
    <Button alignSelf="center">🐌</Button>
    <Button alignSelf="end">🐌</Button>
    <hr />
    <Button alignText="start">🐌</Button>
    <Button alignText="end">🐌</Button>
    <Button alignText="center">🐌</Button>

Override the cursor ​

With the css variable --cursor, you can override the default (pointer).

Emphasize a button that responds to SPACE with autofocus and ENTER with fake-focus ​

If the user is likely to choose a certain button in a given situation, give it the autofocus attribute. This will put the focus on it so that the user can confirm it by pressing SPACE and doesn't need to navigate to it. The button will be emphasized with a contrasting outline. Primary buttons will draw the outline outside their shape for increased emphasis and visibility (A11y).

Make sure to not steal focus from a more important control, and to to visibly return focus to whare it was before after the button is gone. See the Modal component (docs) for a complete example.

If pressing ENTER implicitly activates the button (and only then), give the button a fake-focus attribute. It indicates that "pressing the enter key has the same effect as pressing this button". An example is a "Best match" button under an input where the user can search for matching items. This is implemented in the Pill component

<Button
  ghost
  icon="bi bi-clipboard"
  aria-label="Copy the address"
  @click="alerts.unshift(Date.now())"
/>
<Button
  ghost
  icon="bi bi-eye"
  aria-label="Toggle Preview"
  :aria-pressed="isPreview"
  @click="isPreview = !isPreview"
/>