funkwhale/front/ui-docs/components/ui/button.md

<script setup lang="ts">
import Button from '~/components/ui/Button.vue'
import Layout from '~/components/ui/Layout.vue'

const click = ():Promise<void> => new Promise(resolve => setTimeout(resolve, 1000))
</script>

# Button

Buttons are UI elements that users can interact with to perform actions. Funkwhale uses buttons in many contexts.

```ts
{
  alignText?: 'left' | 'center' | 'right'
  alignSelf?: 'start' | 'center' | 'end'
  thin?: 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
```

## 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

<Layout grid class="preview transparent">

<div style="grid-column: span 3">

```vue-html
<Button>
  Default button
</Button>
```

</div>

<Button>
  Default button
</Button>

</Layout>

### Primary

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

<Layout grid class="preview">

<div style="grid-column: span 3">

```vue-html
<Button primary>
  Primary button
</Button>
```

</div>

<Button primary>
  Primary button
</Button>

</Layout>

### Secondary

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

<Layout grid class="preview secondary">

<div style="grid-column: span 3">

```vue-html
<Button secondary raised>
  Secondary button
</Button>
```

</div>

<Button secondary raised>
  Secondary button
</Button>

</Layout>

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.

<Layout grid class="preview">

<div style="grid-column: span 3">

```vue-html
<Button destructive>
  Destructive button
</Button>
```

</div>

<Button destructive>
  Destructive button
</Button>

</Layout>

## 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
<Button>
  Filled button
</Button>

<Button solid>
  Also filled button
</Button>
```

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

```vue-html
<Button outline secondary>
  Outline button
</Button>
```

<Button outline secondary>
  Outline button
</Button>

### Ghost

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

```vue-html
<Button ghost secondary>
  Ghost button
</Button>
```

<Button ghost secondary>
  Ghost button
</Button>

## Button styles

### Shadow

You can give a button a shadow to add depth.

```vue-html
<Button shadow>
  Shadow button
</Button>
```

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

::: info
This is the default shape. If you don't specify a type, a normal button is rendered.
:::

```vue-html
<Button>
  Normal button
</Button>
```

<Button>
  Normal button
</Button>

### Round

Round buttons have fully rounded edges.

```vue-html
<Button round>
  Round button
</Button>
```

<Button round>
  Round button
</Button>

## Button states

You can pass a state to indicate whether a user can interact with a button.

### Active

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

This can be useful for toggle buttons (if you don't want to use a [Toggle component](toggle))

```vue-html
<Button aria-pressed>
  Active button
</Button>
```

**Default:**

<Button>
  Inactive button
</Button>

<Button aria-pressed>
  Active button
</Button>

---

**Secondary:**

<Button secondary>
  Inactive button
</Button>

<Button secondary aria-pressed>
  Active button
</Button>

---

**Primary:**

<Button primary>
  Inactive button
</Button>

<Button primary aria-pressed>
  Active button
</Button>

### Disabled

Disabled buttons are non-interactive and inherit a less bold color than the one provided. You can apply a disabled state by passing a `disabled` prop.

```vue-html
<Button disabled>
  Disabled button
</Button>
```

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

```vue-html
<Button is-loading>
  Loading button
</Button>
```

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

<Button primary 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.

::: danger
There is no promise rejection mechanism implemented in the `<Button>` component. Make sure the `@click` handler never rejects.
:::

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

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

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

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

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

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

## Icons

You can use [Bootstrap Icons](https://icons.getbootstrap.com/) in your button component

::: info
Icon buttons shrink down to the icon size if you don't pass any content. If you want to keep the button at full width with just an icon, add `width=standard`
:::

```vue-html
<Button icon="bi-three-dots-vertical" />
<Button round icon="bi-x large" />
<Button primary icon="bi-save" buttonWidth/>
<Button destructive icon="bi-trash">
  Delete
</Button>
```

<Layout flex>
<Button icon="bi-three-dots-vertical" />
<Button round secondary icon="bi-x large" />
<Button primary icon="bi-save" buttonWidth/>
<Button destructive icon="bi-trash">
  Delete
</Button>
</Layout>

## Width and alignment

<Layout flex>

```vue-html
    <Button min-content>·</Button>
    <Button small>·</Button>
    <Button buttonWidth>·</Button>
    <Button medium>·</Button>
    <Button auto>·</Button>

    <hr />

    <Button alignSelf="start">·</Button>
    <Button alignSelf="center">·</Button>
    <Button alignSelf="end">·</Button>

    <hr />

    <Button alignText="left">·</Button>
    <Button alignText="center">·</Button>
    <Button alignText="right">·</Button>
```

  <Layout class="preview solid primary" stack no-gap>
    <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="left">🐌</Button>
    <Button alignText="center">🐌</Button>
    <Button alignText="right">🐌</Button>
  </Layout>
</Layout>