Docs

Button

Posted on December 29, 2023  (Last modified on June 20, 2025) • 9 min read • 1,870 words
Component  
Component  
Share via

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

Overview   Arguments   Examples   Stateful Buttons   Sized Buttons   Colored Buttons   Buttons With a Badge   Buttons With an Icon   Outlined Buttons   Buttons With a Tooltip   Buttons With a Collapsible Panel  

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. As an example, the following shortcode displays a tooltip for a dark button with a badge.

Inbox 99+  
markdown 
{{< button color="secondary" tooltip="Click on the inbox to view your unread messages" href="#!" badge="99+" >}}
    Inbox
{{< /button >}}

Arguments  

The shortcode supports the following arguments:

Name Type Required Default Comment
aria-label string Alias for label.
badge string Positioned badge to display on top of the button.
button-size select md v1.0.0      Size of the button. Supported values: [xs, sm, md, lg].
button-state select enabled v1.0.0      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, template.URL Text to be copied to the clipboard when the button is clicked.
collapse string v1.0.0      Use collapse-id instead. ID of the panel to collapse. Cannot be used together with tooltip. Ignored for active/inactive buttons.
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, template.URL, url 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.
id string Unique identifier of the current element.
justify select center Justification of the child elements. Supported values: [start, end, center, between, around, evenly].
label string Assistive label of the element.
link-type select button v1.0.0      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.
size select md v1.0.0      Use button-size instead. Size of the button. Supported values: [sm, md, lg].
spacing bool true Flag to add spacing to the inline element.
state select enabled v1.0.0      Use button-state instead. State of the button. Supported values: [enabled, disabled, active, inactive].
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, hstring.RenderedString, hstring.HTML, template.HTML Title of the element. If the element references a (local) page, the title overrides the referenced page’s title.
toast string v1.0.0      Use toast-id instead. Identifier (ID) of the toast to display when the button is clicked.
toast-id string v1.0.0      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.
type select button v1.0.0      Use link-type instead. Type of the element. Supported values: [link, button].
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.
Name Type Required Default
aria-label string
Alias for label.
badge string
Positioned badge to display on top of the button.
button-size select md
v1.0.0      Size of the button. Supported values: [xs, sm, md, lg].
button-state select enabled
v1.0.0      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, template.URL
Text to be copied to the clipboard when the button is clicked.
collapse string
v1.0.0      Use collapse-id instead. ID of the panel to collapse. Cannot be used together with tooltip. Ignored for active/inactive buttons.
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, template.URL, url
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.
id string
Unique identifier of the current element.
justify select center
Justification of the child elements. Supported values: [start, end, center, between, around, evenly].
label string
Assistive label of the element.
link-type select button
v1.0.0      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.
size select md
v1.0.0      Use button-size instead. Size of the button. Supported values: [sm, md, lg].
spacing bool true
Flag to add spacing to the inline element.
state select enabled
v1.0.0      Use button-state instead. State of the button. Supported values: [enabled, disabled, active, inactive].
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, hstring.RenderedString, hstring.HTML, template.HTML
Title of the element. If the element references a (local) page, the title overrides the referenced page’s title.
toast string
v1.0.0      Use toast-id instead. Identifier (ID) of the toast to display when the button is clicked.
toast-id string
v1.0.0      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.
type select button
v1.0.0      Use link-type instead. Type of the element. Supported values: [link, button].
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.

Examples  

Stateful Buttons  

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

Enabled   Disabled   Active   Inactive  
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.

extra small   small   medium   large  
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.

primary   secondary   success   danger   warning   info   light   dark  
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.

Inbox 99+  
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.

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

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

primary   secondary   success   danger   warning   info   light   dark  
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.

top   bottom   left   right  
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.

 
Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
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 >}}
On this page: