Button

npm install @vrembem/button

@use "@vrembem/button";

Options

Button is built as a Sass module. Sass options are used to control CSS output, while design token CSS variables control the styling of the component. Below are the available configuration options.

Sass

Button comes with the following Sass configuration options that can be set using either the config module or Sass with clause methods.

@use "@vrembem/button" with (
  $config: (
    // Toggle for outputting button--block modifier breakpoint variants
    // @type boolean
    "block-breakpoints": true,

    // Map for outputting button--color-[key] modifier variants
    // @type map
    "color": (
      "default": (
        "color-contrast": white,
        "color-mix": black
      ),
      "primary": tokens.get("palette", "primary"),
      "secondary": tokens.get("palette", "secondary"),
      "neutral": tokens.get("palette", "neutral"),
      "important": tokens.get("palette", "important")
    )
  )
);

Design tokens

Button uses design token CSS variables in a reference and fallback pattern. Variables are referenced in the component's styles but are not directly defined; instead, they are provided with sensible fallbacks.

--vb-button-color

var(--vb-foreground-strong)

--vb-button-color-contrast

var(--vb-background)

--vb-button-color-mix

transparent

--vb-button-size

var(--vb-form-control-size)

--vb-button-border-width

var(--vb-form-control-border-width)

--vb-button-border-radius

var(--vb-form-control-border-radius)

--vb-button-font-size

var(--vb-form-control-font-size)

--vb-button-line-height

var(--vb-form-control-line-height)

--vb-button-padding-y

var(--vb-form-control-padding-y)

--vb-button-padding-x

var(--vb-form-control-padding-x)

--vb-button-gap

var(--vb-spacing-sm)

--vb-button-background

var(--vb-button-color)

--vb-button-foreground

var(--vb-button-color-contrast)

--vb-button-border-color

transparent

--vb-button-box-shadow

none

--vb-button-background-hover

color-mix(in oklch, var(--vb-button-color), var(--vb-button-color-mix) 8%)

--vb-button-foreground-hover

var(--vb-button-foreground)

--vb-button-border-color-hover

var(--vb-button-border-color)

--vb-button-box-shadow-hover

var(--vb-button-box-shadow)

--vb-button-background-focus

var(--vb-button-background)

--vb-button-foreground-focus

var(--vb-button-foreground)

--vb-button-border-color-focus

var(--vb-button-border-color)

--vb-button-box-shadow-focus

var(--vb-button-box-shadow)

--vb-button-background-active

color-mix(in oklch, var(--vb-button-color), var(--vb-button-color-mix) 16%)

--vb-button-foreground-active

var(--vb-button-foreground)

--vb-button-border-color-active

var(--vb-button-border-color)

--vb-button-box-shadow-active

var(--vb-button-box-shadow)

--vb-button-opacity-disabled

var(--vb-form-control-opacity-disabled)

Basic usage

The most basic implementation of the button component consists of the button class that can be applied to <button>, <a role="button"> or <input> elements with a type attribute of "button", "submit" or "reset". Remember to add role="button" to any none semantic buttons as needed.

<button class="button">Button</button>
<a class="button" role="button">Anchor</a>
<input class="button" type="button" value="Input" />
<input class="button" type="submit" value="Submit" />
<input class="button" type="reset" value="Reset" />

Elements within a button are centered vertically and spaced accordingly using the value set by --vb-button-gap (default: 0.5em). When elements are added inside a button, the button's text should also be wrapped in a <span> so that it can be spaced properly.

<button class="button">
  <svg>...</svg>
  <span>Button</span>
  <span class="arrow"></span>
</button>

Disabled

When disabled using the disabled attribute, a button will inherit styles to visually appear noninteractive.

<button class="button" disabled>Button</button>

Loading

Buttons can also be given a loading state by adding the is-loading state class. This is useful when a button has an action that has a delayed response in order to give users a visual indicator that their action is being processed.

<button class="button is-loading" disabled>Button</button>

Keep in mind that the is-loading state class will not work on <input type="button"> since it uses the ::after pseudo-element to display the loading spinner.

button--color-[key]

Modifiers for changing the look and feel of a button. These are usually done with different background and text colors. These modifiers are generated using key/value pairs of the button-color config options map.

<button class="button button--color-primary">Button</button>
<button class="button button--color-secondary">Button</button>
<button class="button button--color-neutral">Button</button>
<button class="button button--color-important">Button</button>

Available variants

• button--color-primary
• button--color-secondary
• button--color-neutral
• button--color-important

button--variant-[key]

Variant modifiers change the visual style of a button without affecting its color. They can be composed with color modifiers.

<button class="button button--variant-outline">Button</button>
<button class="button button--variant-subtle">Button</button>

Available variants

• button--variant-outline
• button--variant-subtle

button--icon

Adds styles that make icon-only buttons have equal padding. This will result in a square button if the icon used also has an equal width and height.

<button class="button button--icon">
  <svg>...</svg>
</button>

Icon modifiers can also be combined with size modifiers for further composability.

<button class="button button--icon button--size-sm">...</button>
<button class="button button--icon">...</button>
<button class="button button--icon button--size-lg">...</button>

button--size-[key]

Adjust the size of a button by increasing or decreasing its padding and font-size. These modifiers are generated using key/value pairs of the button-size config options map.

<button class="button button--size-sm">Button</button>
<button class="button">Button</button>
<button class="button button--size-lg">Button</button>

Available variants

• button--size-sm
• button--size-lg

button--block

Modifier that gives buttons a "block" appearance so that it spans the full width of its container.

<button class="button button--block">Button</button>

Breakpoint variants

These modifiers come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map. Breakpoint variants output can be toggled using the button-block-breakpoints config option (default: true).

<button class="button lg:button--block">Button</button>

Available variants

• xs:button--block
• sm:button--block
• md:button--block
• lg:button--block
• xl:button--block