Skip to content
Blueprint

Button

Buttons are used to trigger an action or event, such as submitting a form, opening a modal, or serving as a link to another page.

<Button>Button</Button>

API Reference

This component is based on the <button> and <a> HTML elements. The following are the props that can be passed to the component.

Prop Type Default
variant
"contained" | "outlined" | "subtle" | "text" "contained"
size
"sm" | "md" | "lg" "md"
title
string —
icon
boolean false
href
string —
disabled
boolean false

Accessibility

The <Button> component has some accessibility features that are important to consider when implementing it in your project. The following are some of the key accessibility features that are included in the component:

  • When the button renders as a <button> element, the component includes the a type property that can be changed and defaults to button. This is important for screen readers to understand the purpose of the button.
  • When a button has the icon prop set to true, the button will omit the text and only display the icon. The text will still be included in the button for screen readers to understand the purpose of the button.
  • You can use the title prop to provide a tooltip for the button. This is useful for providing additional context about the purpose of a button, especially so with icon buttons.

Examples

Variants

Use the variant prop to adjust the visual style. Buttons come in the following variants: contained, outlined, subtle, text, and icon. Variants should be added, removed, and tweaked as necessary based on the needs of the project.

<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="subtle">Subtle</Button>
<Button variant="text">Text</Button>

Sizes

Use the size prop to adjust the size. Buttons come in the following different sizes: sm, md, and lg. By default, buttons will use md unless specified. Sizes should be added, removed, and tweaked as necessary based on the needs of the project.

<Button size="sm">Button</Button>
<Button>Button</Button>
<Button size="lg">Button</Button>

Icon

Use the icon prop to make the button into an icon button. Button Icons are buttons that only contain an icon. They are useful for situations where you want to provide a button that is only an icon, such as in a toolbar. By adding the btn-icon class, the button will have a 1:1 aspect ration and the text will be omitted and used only for screen-reader purposes.

---
import { Icon } from '@astrojs/starlight/components'
---


<Button icon variant="subtle" title="More Information">
  <Icon name="information" />
  More Information
</Button>

Use the href prop to convert a button to a link element. This is useful when you want to use a button style to navigate to another page.

Button 
<Button href="#">Button</Button>

On Dark Backgrounds

Buttons can be used on dark backgrounds by adding the dark class to the an ancestor DOM node. THis will invert the colors of the pagination component.

<Button>Button</Button>

Astro Component

Depending on the framework, it’s sometimes beneficial to use a component for generating the button. In this case, we have put together the following Astro component to serve as a blueprint for how you could possibly set up a Button component, and what properties to consider.

Button.astro
---
import type { HTMLTag, Polymorphic } from 'astro/types'


type Props<Tag extends HTMLTag> = Polymorphic<{
  /**
    The HTML tag to render for the component. By default the component will render as a `button` unless `href` is defined, at which point it will render as an `a`.
  */
  as: Tag
  /**
    The variant the button will take. Corresponds to the design system.
  */
  variant?: 'contained' | 'outlined' | 'subtle' | 'text'
  /**
    The size of the button. Corresponds to the design system.
  */
  size?: 'sm' | 'md' | 'lg'
  /**
    The tooltip/assistive text to display on the button.
  */
  title?: string
  /**
    Whether the button should be an icon only button or not. If `true`, the button will omit the text, become a 1:1 aspect ratio, and only display the icon.
  */
  icon?: boolean
  /**
    The URL to link to. Passing in a value will cause the element to render as an anchor.
  */
  href?: string
  /**
    Button type (if applicable). Do not add a type if `href` is set.
  */
  type?: 'button' | 'submit' | undefined
  /**
    Whether the button is disabled or not.
  */
  disabled?: boolean
}>


const {
  as: Tag,
  variant = 'contained',
  size = 'md',
  title,
  icon = false,
  href = undefined,
  type = href ? undefined : 'button',
  disabled = false,
  class: className,
  ...attrs
} = Astro.props


const Element = Tag ? Tag : href && !disabled ? 'a' : 'button'
---


<Element
  href={!disabled ? href : undefined}
  disabled={disabled}
  type={type}
  title={title}
  class:list={[
    {
      'btn-contained': variant === 'contained',
      'btn-outlined': variant === 'outlined',
      'btn-subtle': variant === 'subtle',
      'btn-text': variant === 'text',
      'btn-icon': icon,
      'btn-sm': size === 'sm',
      'btn-lg': size === 'lg',
    },
    className,
  ]}
  data-component="Button"
  {...attrs}
>
  <slot />
</Element>