Buttons

Spruce comes with button variations for color, emphasis, size, width and state, and it can generate your own color variants.

You can use three solid color variants: primary, secondary and danger (new in v3). To overwrite the colors, see the configurable variables section.

<button type="button" class="btn btn--primary">Primary</button>
<a href="https://conedevelopment.com" class="btn btn--secondary">Secondary</a>
<button type="button" class="btn btn--danger">Delete</button>

Use the btn--outline-* modifier class for outlined buttons. If you want to have more control over the look, use the following specific color values under the btn at the $colors map, like in this example:

@use 'sprucecss/scss/spruce' with (
  $colors: (
    'btn': (
      'dark-background': hsl(0deg 0% 0%),
      'dark-background-hover': hsl(0deg 0% 20%),
      'dark-foreground': hsl(0deg 0% 100%),
      'dark-outline-border': hsl(260deg 4% 70%),
      'dark-outline-foreground': hsl(0deg 0% 0%),
      'dark-outline-foreground-hover': hsl(0deg 0% 100%),
      'dark-outline-background-hover': hsl(0deg 0% 0%),
      'dark-outline-focus-ring': hsl(295deg 100% 50%),
    ),
  ),
);

To make a custom outline button, you need to use the btn-variant-outline mixin.

<button type="button" class="btn btn--outline-primary">Primary</button>
<a href="https://conedevelopment.com" class="btn btn--outline-secondary">Secondary</a>
<button type="button" class="btn btn--outline-danger">Delete</button>

New in v3. Lower-emphasis variants for secondary actions. Soft buttons have a tinted background; ghost buttons are transparent until hovered. Both mix the variant color at runtime with color-mix(), so they follow the dark mode and the styles.

<button type="button" class="btn btn--soft-primary">Soft primary</button>
<button type="button" class="btn btn--ghost-primary">Ghost primary</button>

New in v3. The btn--link modifier looks like a link but keeps the button’s size and alignment, so it lines up with other buttons.

<button type="button" class="btn btn--link">Cancel</button>

Use the btn--*-shadow modifier class to add a shadow to the button. This class is generated automatically if there is a color value under the btn section with the *-shadow key in the $colors map.

<button type="button" class="btn btn--primary btn--primary-shadow">Primary</button>
<a href="https://conedevelopment.com" class="btn btn--secondary btn--secondary-shadow">Secondary</a>

Spruce comes with three button sizes: small, regular and large. For the regular size, you don't need a modifier. Use the btn--sm class for small and the btn--lg class for large buttons.

<button type="button" class="btn btn--primary btn--sm">Small</button>
<button type="button" class="btn btn--primary">Regular</button>
<button type="button" class="btn btn--primary btn--lg">Large</button>

New in v3. Use the btn--pill modifier for fully rounded buttons.

<button type="button" class="btn btn--primary btn--pill">Pill</button>

New in v3. Add the btn--loading class while an action runs: the label becomes invisible (but keeps the button’s width), a spinner appears in the text color, and the clicks are blocked. Set aria-busy="true" too, and announce the result when it finishes.

<button type="button" class="btn btn--primary btn--loading" aria-busy="true">Saving</button>

To disable any button element, use the disabled boolean attribute. The disabled style is dimmer (opacity: 0.5;, configurable with the disabled-opacity key of $btn) and has pointer-events: none; to prevent user actions.

The disabled attribute doesn't work on links, so use the btn--disabled modifier class (or aria-disabled="true", which gets the same style). Also, omit the href attribute.

<button type="button" class="btn btn--primary" disabled>Disabled button</button>
<button type="button" class="btn btn--secondary" disabled>Disabled button</button>
<a class="btn btn--primary btn--disabled" aria-disabled="true">Disabled button</a>
<a class="btn btn--secondary btn--disabled" aria-disabled="true">Disabled button</a>

To display a block button, you can use the btn--block modifier class.

<button type="button" class="btn btn--primary btn--block">Block button</button>
<button type="button" class="btn btn--secondary btn--block">Block button</button>

To use any icon with Spruce, you must specify it in image format, preferably in SVG, because we set its height and width. Use with the btn__icon class on the image. Place it before (left) or after the caption (right) depending on the position.

The .btn has inline-flex display with a gap value.

<button type="button" class="btn btn--primary">
    <svg class="btn__icon">...</svg>
    Read more
</button>
<button type="button" class="btn btn--secondary">
    Read more
    <svg class="btn__icon">...</svg>
</button>

To make an only icon button use the btn--icon modifier class. If you create an icon button, use aria-label to add a caption.

<button class="btn btn--secondary btn--icon" aria-label="Copy Text">
    <svg class="btn__icon">...</svg>
    Read more
</button>

New in v3. Wrap related buttons in a .btn-group to attach them. Use .btn-group--vertical to stack them. Give the group a role="group" and an aria-label; for toggle buttons, use aria-pressed.

<div class="btn-group" role="group" aria-label="Text alignment">
    <button type="button" class="btn btn--outline-primary" aria-pressed="true">Left</button>
    <button type="button" class="btn btn--outline-primary" aria-pressed="false">Center</button>
    <button type="button" class="btn btn--outline-primary" aria-pressed="false">Right</button>
</div>

There are default variables that you can configure to customize the button's look. New in v3: box-shadow, disabled-opacity, letter-spacing and line-height.

@use 'sprucecss/scss/spruce' with (
  $btn: (
    'border-radius': 0.25rem,
    'font-weight': 700,
    'letter-spacing': 0.02em,
  ),
);

Spruce manages the colors in a separate Sass map named $colors (under the btn group). In custom property mode, you can also change any button value at runtime through the style hooks, like --spruce-btn-padding.

You can create new button color variants with the btn-variant mixin. First, declare the new button's colors in the $colors map under the btn group. Then call the mixin on the preferred selector. The btn-variant-outline, btn-variant-soft and btn-variant-ghost mixins create the other variants from the same colors.

@use 'sprucecss/scss/spruce' with (
  $colors: (
    'btn': (
      'brand-background': hsl(330deg 80% 50%),
      'brand-background-hover': hsl(330deg 80% 44%),
      'brand-foreground': hsl(0deg 0% 100%),
    ),
  ),
);

.btn--brand { @include btn-variant('brand'); }
.btn--outline-brand { @include btn-variant-outline('brand'); }
.btn--soft-brand { @include btn-variant-soft('brand'); }
.btn--ghost-brand { @include btn-variant-ghost('brand'); }

For more information, visit the mixins page.