---
title: Buttons
description: Buttons provide styled link elements for calls to action in documentation. Use buttons to highlight important navigation points, downloads, or external...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/buttons
products:
  - Elastic Docs Builder
---

# Buttons
Buttons provide styled link elements for calls to action in documentation. Use buttons to highlight important navigation points, downloads, or external resources.
<button>
  [Getting Started](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/get-started/introduction)
</button>


## Basic button

A button wraps a standard Markdown link with button styling:
<tab-set>
  <tab-item title="Output">
    <button>
      [Syntax Guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax)
    </button>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{button}
    [Get Started](/get-started)
    :::
    ```
  </tab-item>
</tab-set>


## Button types

Two button variants are available:
- **Primary** (default): Filled blue background with white text, used for main calls to action.
- **Secondary**: Blue border with transparent background, used for secondary actions.

<tab-set>
  <tab-item title="Output">
    <button-group>
      <button>
        [Quick Reference](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/quick-ref)
      </button>

      <button>
        [Syntax Guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax)
      </button>
    </button-group>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ::::{button-group}
    :::{button}
    [Primary Action](/primary)
    :::
    :::{button}
    :type: secondary
    [Secondary Action](/secondary)
    :::
    ::::
    ```
  </tab-item>
</tab-set>


## Button groups

Use the `{button-group}` directive to display multiple buttons in a row:
<tab-set>
  <tab-item title="Output">
    <button-group>
      <button>
        [Admonitions](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/admonitions)
      </button>

      <button>
        [Dropdowns](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/dropdowns)
      </button>
    </button-group>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ::::{button-group}
    :::{button}
    [Elastic Fundamentals](/get-started)
    :::
    :::{button}
    :type: secondary
    [Upgrade Versions](/deploy-manage/upgrade)
    :::
    ::::
    ```
  </tab-item>
</tab-set>


## Alignment


### Single button alignment

Control the horizontal alignment of standalone buttons with the `:align:` property:
<tab-set>
  <tab-item title="Output">
    <button>
      [Links](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/links)
    </button>

    <button>
      [Images](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/images)
    </button>

    <button>
      [Tables](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/tables)
    </button>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{button}
    :align: left
    [Left (default)](/example)
    :::

    :::{button}
    :align: center
    [Center](/example)
    :::

    :::{button}
    :align: right
    [Right](/example)
    :::
    ```
  </tab-item>
</tab-set>


### Button group alignment

Button groups also support the `:align:` property:
<tab-set>
  <tab-item title="Output">
    <button-group>
      <button>
        [Code Blocks](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/code)
      </button>

      <button>
        [Tabs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3804/syntax/tabs)
      </button>
    </button-group>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    ::::{button-group}
    :align: center
    :::{button}
    [Centered Group](/example)
    :::
    :::{button}
    :type: secondary
    [Second Button](/example)
    :::
    ::::
    ```
  </tab-item>
</tab-set>


## External links

External links (URLs outside elastic.co) automatically open in a new tab, just like regular links:
<tab-set>
  <tab-item title="Output">
    <button>
      [Visit GitHub](https://github.com/elastic)
    </button>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{button}
    [Visit GitHub](https://github.com/elastic)
    :::
    ```
  </tab-item>
</tab-set>

External links include `target="_blank"` and `rel="noopener noreferrer"` attributes for security.

## Cross-repository links

Buttons support [cross-repository links](/elastic/docs-builder/pull/3804/syntax/links#cross-repository-links) using the `scheme://path` syntax:
<tab-set>
  <tab-item title="Output">
    <button>
      [Getting Started Guide](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/get-started/introduction)
    </button>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{button}
    [Getting Started Guide](docs-content://get-started/introduction.md)
    :::
    ```
  </tab-item>
</tab-set>

Cross-links are resolved at build time to their target URLs in the documentation site.

## Properties reference


### Button properties


| Property  | Required | Default   | Description                                                                |
|-----------|----------|-----------|----------------------------------------------------------------------------|
| (content) | Yes      | -         | A Markdown link `[text](url)` that becomes the button.                     |
| `:type:`  | No       | `primary` | Button variant: `primary` (filled) or `secondary` (outlined).              |
| `:align:` | No       | `left`    | Horizontal alignment for standalone buttons: `left`, `center`, or `right`. |


### Button group properties


| Property  | Required | Default | Description                                                             |
|-----------|----------|---------|-------------------------------------------------------------------------|
| `:align:` | No       | `left`  | Horizontal alignment of the button group: `left`, `center`, or `right`. |