# Button

Use the button shortcode to display a button with a hyperlink.

## Overview

Use the `button` shortcode to display a button with a hyperlink. The inner content is used as button title. The button supports an optional badge and tooltip.

### Stateful buttons

Set the `button-state` argument to change the appearance and behavior of the button.

```markdown
{{< button color="primary" href="#!" button-state="enabled" >}}Enabled{{< /button >}}
{{< button color="primary" href="#!" button-state="disabled" >}}Disabled{{< /button >}}
{{< button color="primary" href="#!" button-state="active" >}}Active{{< /button >}}
{{< button color="primary" href="#!" button-state="inactive" >}}Inactive{{< /button >}}
```

### Sized buttons

Set the `button-size` argument to resize the button.

```markdown
{{< button color="primary" href="#!" button-size="xs" >}}extra small{{< /button >}}
{{< button color="primary" href="#!" button-size="sm" >}}small{{< /button >}}
{{< button color="primary" href="#!" button-size="md" >}}medium{{< /button >}}
{{< button color="primary" href="#!" button-size="lg" >}}large{{< /button >}}
```

### Colored buttons

Set the `color` argument to define the background color with a matching title color.

```markdown
{{< button color="primary" href="#!" button-size="sm" >}}primary{{< /button >}}
{{< button color="secondary" href="#!" button-size="sm" >}}secondary{{< /button >}}
{{< button color="success" href="#!" button-size="sm" >}}success{{< /button >}}
{{< button color="danger" href="#!" button-size="sm" >}}danger{{< /button >}}
{{< button color="warning" href="#!" button-size="sm" >}}warning{{< /button >}}
{{< button color="info" href="#!" button-size="sm" >}}info{{< /button >}}
{{< button color="light" href="#!" button-size="sm" >}}light{{< /button >}}
{{< button color="dark" href="#!" button-size="sm" >}}dark{{< /button >}}
```

### Buttons with a badge

Set the `badge` argument to add a badge to the top right of the button.

```markdown
{{< button color="secondary" href="#!" badge="99+" >}}
    Inbox
{{< /button >}}
```

### Buttons with an icon

Set the `icon` argument to add an icon to the button. Use `order` to determine the position of the icon relative to the title. Omit the title to show an icon only.

```markdown
{{< button icon="fab linkedin" cue=false order="first" href="https://linkedin.com" >}}
    LinkedIn
{{< /button >}}

{{< button icon="fab linkedin" cue=false order="last" href="https://linkedin.com" >}}
    LinkedIn
{{< /button >}}

{{< button icon="fab linkedin" href="https://linkedin.com" />}}
```

Use `justify` to adjust the layout of the icon and button title.

```markdown
{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="start" href="https://linkedin.com" >}}LinkedIn{{< /button >}}

{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="end" href="https://linkedin.com" >}}LinkedIn{{< /button >}}

{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="center" href="https://linkedin.com" >}}LinkedIn{{< /button >}}

{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="between" href="https://linkedin.com" >}}LinkedIn{{< /button >}}

{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="around" href="https://linkedin.com" >}}LinkedIn{{< /button >}}

{{< button icon="fab linkedin" cue=false class="col-12 col-sm-8 col-md-4 offset-sm-2 offset-md-4"
    justify="evenly" href="https://linkedin.com" >}}LinkedIn{{< /button >}}
```

### Outlined buttons

Set the `outline` argument to `true` to adjust the style of the button.

```markdown
{{< button color="primary" href="#!" button-size="sm" outline="true" >}}primary{{< /button >}}

{{< button color="secondary" href="#!" button-size="sm" outline="true" >}}secondary{{< /button >}}

{{< button color="success" href="#!" button-size="sm" outline="true" >}}success{{< /button >}}

{{< button color="danger" href="#!" button-size="sm" outline="true" >}}danger{{< /button >}}

{{< button color="warning" href="#!" button-size="sm" outline="true" >}}warning{{< /button >}}

{{< button color="info" href="#!" button-size="sm" outline="true" >}}info{{< /button >}}

{{< button color="light" href="#!" button-size="sm" outline="true" >}}light{{< /button >}}

{{< button color="dark" href="#!" button-size="sm" outline="true" >}}dark{{< /button >}}
```

### Buttons with a tooltip

Set the `tooltip` argument in conjunction with `placement` to show a tooltip when hovering over the button.

```markdown
{{< button color="secondary" tooltip="Click on the inbox to view your unread messages" href="#!"
    placement="top" >}}top{{< /button >}}

{{< button color="secondary" tooltip="Click on the inbox to view your unread messages" href="#!"
    placement="bottom" >}}bottom{{< /button >}}

{{< button color="secondary" tooltip="Click on the inbox to view your unread messages" href="#!"
    placement="left" >}}left{{< /button >}}

{{< button color="secondary" tooltip="Click on the inbox to view your unread messages" href="#!"
    placement="right" >}}right{{< /button >}}
```

### Buttons with a collapsible panel

Reveal or hide a collapsible panel by linking the panel's `id` to the button with the argument `collapse-id`.

```markdown
{{< button color="secondary" collapse-id="collapse-1" >}}
    Collapse
{{< /button >}}

{{< collapse id="collapse-1" class="p-3 border rounded" >}}
    Some placeholder content for the collapse component. This panel is
    *hidden by default* but revealed when the user activates the relevant
    trigger.
{{< /collapse >}}
```

## Styling

The file `assets/scss/components/_button.scss` defines the Hinode-specific styling of the `button` shortcode. Check the [Bootstrap documentation](https://getbootstrap.com/docs/5.3/components/button/#css) for additional styling options.

```scss
/* Set hover color for primary button to white (overrides color contrast defined in mixin) */
.btn-outline-primary:hover,
.btn-primary:focus,
.btn-primary:active,
.btn-primary.active,
.open > .dropdown-toggle.btn-primary {
    color: #fff if($enable-important-utilities, !important, null);
}

.btn-social {
    background-color: transparent;
    
    --bs-btn-bg: transparent;
    --bs-btn-border-width: none;
    --bs-btn-color: var(--bs-secondary);
    --bs-btn-border-color: none;
    --bs-btn-hover-bg: none;
    --bs-btn-hover-border-color: none;
    --bs-btn-active-bg: none;
    --bs-btn-active-border-color: none;
}

.btn-social:hover,
.btn-social:focus,
.btn-social:active,
.btn-social.active,
.open > .dropdown-toggle.btn-primary {
    background-color: transparent;
    color: var(--bs-primary) if($enable-important-utilities, !important, null);
}

a.btn {
    margin-top: $spacer * .25;
    margin-bottom: $spacer * .25;
}

.btn-close {
    background-color: transparent if($enable-important-utilities, !important, null);
    background-image: var(--#{$prefix}btn-close-bg) if($enable-important-utilities, !important, null);
    background-position: center if($enable-important-utilities, !important, null);
    background-repeat: no-repeat if($enable-important-utilities, !important, null);
    background-size: $btn-close-width if($enable-important-utilities, !important, null);
}

.btn-link {
    --bs-btn-padding-x: 0;
    --bs-btn-padding-y: 0;

    margin: 0 !important;
}

.btn-xs {
  @include button-size($btn-padding-y-xs, $btn-padding-x-xs, $btn-font-size-xs, $btn-border-radius-xs);
}

.btn {
    --bs-border-radius: #{$theme-border-radius};
}
```

## Arguments

The shortcode supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `aria-label` | string |  |  | Alias for label. |
| `badge` | string |  |  | Positioned badge to display on top of the button. |
| `button-size` | select |  | `md` | Size of the button. Supported values: [`xs`, `sm`, `md`, `lg`]. |
| `button-state` | select |  | `enabled` | State of the button. Supported values: [`enabled`, `disabled`, `active`, `inactive`]. |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `clipboard` | string |  |  | Text to be copied to the clipboard when the button is clicked. |
| `collapse-id` | string |  |  | ID of the panel to collapse. Cannot be used together with tooltip. Ignored for active/inactive buttons. |
| `color` | select |  | `primary` | Theme color of the element. Supported values: [`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `white`, `black`, `body`, `body-tertiary`]. |
| `cue` | bool |  |  | Flag to indicate if an external link should show a visual cue, defaults to the setting `main.externalLinks.cue` in the site's parameters. |
| `href` | string |  |  | Address for the button or hyperlink. When set for a card group, a button is added if the list exceeds the maximum number of cards to display. |
| `icon` | string |  |  | Icon to include. You can use shorthand notation such as `fas sort` to include a Font Awesome icon. The argument also supports files with an `.svg` or `.json` extension. |
| `icon-class` | string |  |  | Class attributes of the icon. Use these to add modifiers such as `fa-2x` and `fa-flip-horizontal`. |
| `id` | string |  |  | Unique identifier of the current element. |
| `justify` | select |  | `start` | Justification of the child elements. Supported values: [`start`, `end`, `center`, `between`, `around`, `evenly`]. |
| `label` | string |  |  | Assistive label of the element. |
| `link-type` | select |  | `button` | Style of the link. Supported values: [`button`, `link`]. |
| `order` | select |  | `last` | Order of the illustration. Supported values: [`first`, `last`]. |
| `outline` | bool |  |  | Flag indicating the element should use an outline color instead of a fill color. |
| `placement` | select |  | `top` | Position of the tooltip. Supported values: [`top`, `bottom`, `left`, `right`]. |
| `relref` | string |  |  | Name of the page to link to. Replaces `href` with a relative link if set. |
| `spacing` | bool |  | `true` | Flag to add spacing to the inline element. |
| `tab` | bool |  |  | Flag to indicate if an external link should open in a new tab, defaults to setting `main.externalLinks.tab` in the site's parameters. |
| `title` | string |  |  | Title of the element. If the element references a (local) page, the title overrides the referenced page's title. |
| `toast-id` | string |  |  | Identifier (`id`) of the toast to display when the button is clicked. |
| `tooltip` | string |  |  | Text to display in a tooltip. Cannot be used together with collapse-id. Ignored for active/inactive buttons. |
| `wrapper` | string |  |  | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |