Utility

The utility component provides a set of atomic classes that specialize in a single function.

npm version

Source Code

npm install @vrembem/utility
@use "@vrembem/utility";

Intro

Once loaded, the utility component provides a number of classes that can be used independently or to supplement other loaded components.

<!-- Using utility classes independently -->
<div class="padding background-shade border radius">
  <p class="text-bold text-align-center">...</p>
</div>

<!-- Using utility classes with other components -->
<div class="grid flex-justify-center">
  <div class="grid__item span-auto">...</div>
  <div class="grid__item span-auto">...</div>
</div>

Each utility has a corresponding $output-[module] and $class-[module] variable that determines whether or not the module is output and it’s class name. Output variable inherits their default value from $output.

// Will disable the output of the color module
@use "@vrembem/utility" with (
  $output-color: false
);

// Will disable all modules, but enables the color module
@use "@vrembem/utility" with (
  $output: false,
  $output-color: true
);

Global Variables

Setting these variables will apply to all utility modules.

Variable Default Description
$prefix-utility null String to prefix all utility classes with.
$output true Toggles the default output of all modules.
$breakpoints core.$breakpoints Ref ↓ A map of breakpoints used by utilities that provide breakpoint specific variations such as the display and span utilities.
$gap core.$gap1em Used as the default spacing for margin and padding utilities.
$gap-map core.$gap-map Ref ↓ Used to build gap variants for margin and padding utilities.

$breakpoints

A map of breakpoints used by utilities that provide breakpoint specific variations such as the display and span utilities.

// Inherited from: core.$breakpoints
$breakpoints: (
  "xs": 480px,
  "sm": 620px,
  "md": 760px,
  "lg": 990px,
  "xl": 1380px
) !default;

$gap-map

Used to build gap variants for flex-gap, flex-gap-x, flex-gap-y, gap-x, gap-y, margin and padding utilities.

// Inherited from: core.$gap-map
$gap-map: (
  "none": 0,
  "xs": 0.25em,
  "sm": 0.5em,
  "md": 1em,
  "lg": 1.5em,
  "xl": 2em
) !default;

Modules

The utility component consists of a number of modules with their own set of specific customizable class and output variables.

background

Applies background color property. Most options include light, lighter, dark and darker variants.

<div class="background-primary-lighter"></div>
<div class="background-primary-light"></div>
<div class="background-primary"></div>
<div class="background-primary-dark"></div>
<div class="background-primary-darker"></div>
...
Variable Default Description
$output-background $outputtrue Toggles the output of this module.
$class-background "background" String to use for the class name of the background utility.

border

Applies border property with optional sides variants.

<div class="border"></div>
<div class="border-top"></div>
<div class="border-right"></div>
<div class="border-bottom"></div>
<div class="border-left"></div>
Variable Default Description
$output-border $outputtrue Toggles the output of this module.
$class-border "border" String to use for the class name of the border utility.

border-none

Remove border styles with border-none utilities and optional side variants.

<div class="border-none"></div>
<div class="border-top-none"></div>
<div class="border-right-none"></div>
<div class="border-bottom-none"></div>
<div class="border-left-none"></div>

border-color

Add border color utilities with light, dark and darker variants.

<div class="border border-color-light"></div>
<div class="border"></div>
<div class="border border-color-dark"></div>
<div class="border border-color-darker"></div>
<div class="border border-color-invert-light"></div>
<div class="border border-color-invert"></div>
<div class="border border-color-invert-dark"></div>
<div class="border border-color-invert-darker"></div>

border-radius

Applies border-radius styles with optional corner variants. The value used by the radius utility is pulled from the core.$border-radius variable.

<!-- Applied to all corners -->
<div class="radius"></div>

<!-- Applied to all corners on a specific side -->
<div class="radius-top"></div>
<div class="radius-right"></div>
<div class="radius-bottom"></div>
<div class="radius-left"></div>

<!-- Applied to specific corners -->
<div class="radius-top-left"></div>
<div class="radius-top-right"></div>
<div class="radius-bottom-right"></div>
<div class="radius-bottom-left"></div>
Variable Default Description
$output-border-radius $outputtrue Toggles the output of this module.
$class-border-radius "radius" String to use for the class name of the border-radius utility.

radius-circle

Applies the maximum value to border-radius with optional corner variants. The value used by radius-circle utility is pulled from the core.$border-radius-circle variable.

<!-- Applied to all corners -->
<div class="radius-circle"></div>

<!-- Applied to all corners on a specific side -->
<div class="radius-circle-top"></div>
<div class="radius-circle-right"></div>
<div class="radius-circle-bottom"></div>
<div class="radius-circle-left"></div>

<!-- Applied to specific corners -->
<div class="radius-circle-top-left"></div>
<div class="radius-circle-top-right"></div>
<div class="radius-circle-bottom-right"></div>
<div class="radius-circle-bottom-left"></div>

radius-square

Removes border-radius by setting it’s value to 0 with optional corner variants.

<!-- Applied to all corners -->
<div class="radius-square"></div>

<!-- Applied to all corners on a specific side -->
<div class="radius-square-top"></div>
<div class="radius-square-right"></div>
<div class="radius-square-bottom"></div>
<div class="radius-square-left"></div>

<!-- Applied to specific corners -->
<div class="radius-square-top-left"></div>
<div class="radius-square-top-right"></div>
<div class="radius-square-bottom-right"></div>
<div class="radius-square-bottom-left"></div>

box-shadow

Applies different levels of elevation through box-shadow styles.

<div class="elevate"></div>
<div class="elevate-flat"></div>
<div class="elevate-1dp"></div>
<div class="elevate-4dp"></div>
<div class="elevate-8dp"></div>
<div class="elevate-16dp"></div>
<div class="elevate-24dp"></div>
Variable Default Description
$output-box-shadow $outputtrue Toggles the output of this module.
$class-box-shadow "elevate" String to use for the class name of the box-shadow utility.

color

Applies text color property. Most options include light, lighter, dark and darker variants.

Color Color light Color primary Color primary Color primary Color primary Color primary Color secondary Color secondary Color secondary Color secondary Color secondary Color shade Color shade Color shade Color night Color night Color night Color info Color info Color info Color info Color info Color success Color success Color success Color success Color success Color caution Color caution Color caution Color caution Color caution Color danger Color danger Color danger Color danger Color danger Color black Color white Color transparent
Color invert Color invert dark Color primary Color primary Color primary Color primary Color primary Color secondary Color secondary Color secondary Color secondary Color secondary Color shade Color shade Color shade Color night Color night Color night Color info Color info Color info Color info Color info Color success Color success Color success Color success Color success Color caution Color caution Color caution Color caution Color caution Color danger Color danger Color danger Color danger Color danger Color black Color white Color transparent
<span class="color"></span>
<span class="color-subtle"></span>
<span class="color-primary-light"></span>
<span class="color-primary"></span>
<span class="color-primary-dark"></span>
...
Variable Default Description
$output-color $outputtrue Toggles the output of this module.
$class-color "color" String to use for the class name of the color utility.

display

Display utilities allow you to toggle the display property on an element with an optional breakpoint conditional.

.display-[property]-[breakpoint]
[property]

inline

flex

inline-flex

block

inline-block

none

[breakpoint]

xs ...480px

sm ...620px

md ...760px

lg ...990px

xl ...1380px

<div class="display-block display-none-xs">
  <p>Small Mobile</p>
</div>

<div class="display-none display-block-xs display-none-sm">
  <p>Small Mobile => Mobile</p>
</div>

<div class="display-none display-block-sm display-none-md">
  <p>Mobile => Tablet</p>
</div>

<div class="display-none display-block-md display-none-lg">
  <p>Tablet => Desktop</p>
</div>

<div class="display-none display-block-lg display-none-xl">
  <p>Desktop => Large Desktop</p>
</div>

<div class="display-none display-block-xl">
  <p>Large Desktop</p>
</div>
Variable Default Description
$output-display $outputtrue Toggles the output of this module.
$class-display "display" String to use for the class name of the display utility.
$display-properties Sass Map Ref ↓ A list of display properties to output along with their breakpoint variants.

$display-properties

A list of display properties to output along with their breakpoint variants.

$display-properties: (
  inline,
  flex,
  inline-flex,
  block,
  inline-block,
  none
) !default;

flex

The flex utility is a great way to adjust individual flex properties on components that use flex layout. Flex utilities fall under two categories: 1) those that are appleid to a flexbox container and 2) those that are applied to flexbox children elements directly. These are some available flex property based utilities:

Applied to flex containers

  • flex & flex-inline - Sets the display flex or flex-inline property.
  • flex-direction-[key] - Applies a flex direction property with the provided key as the value.
  • flex-nowrap - Applies the flex-wrap property with the value of nowrap.
  • flex-wrap - Applies the flex-wrap property with the value of wrap.
  • flex-wrap-reverse - Applies the flex-wrap property with the value of wrap-reverse.
  • flex-justify-[key] - Applies the justify-content property with the provided key as the value.
  • flex-align-[key] - Applies the align-items property with the provided key as the value.
  • flex-items-[key] - Gives all direct children the flex property to either share the container space equally (equal) or keep their content’s width (auto).

Applied to flex children elements

  • flex-order-[key] - Applies the order property with the provided key as the value.
  • flex-grow-[key] - Applies the flex-grow property with the provided key as the value.
  • flex-shrink-[key] - Applies the flex-shrink property with the provided key as the value.
  • flex-basis-[key] - Applies the flex-basis property with the provided key (0   auto) as the value.
  • flex-self-[key] - Applies the align-self property with the provided key as the value.
Variable Default Description
$output-flex $outputtrue Toggles the output of this module.
$class-flex "flex" String to use for the class name of the flex utility.
$flex-order-count 12 Number of flex order utilities to output starting from 1.
$flex-grow-count 6 Number of flex-grow utilities to output starting from 0.
$flex-shrink-count 6 Number of flex-shrink utilities to output starting from 0.

flex-direction-[value]

Applies a flex direction property with the provided key value.

  • flex-direction-row
  • flex-direction-row-reverse
  • flex-direction-column
  • flex-direction-column-reverse
1
2
3
<div class="flex-direction-row">...</div>
1
2
3
<div class="flex-direction-row-reverse">...</div>
1
2
<div class="flex-direction-column">...</div>
1
2
<div class="flex-direction-column-reverse">...</div>

flex-wrap

Applies various flex-wrap property values.

  • flex-nowrap - Applies the flex-wrap property with the value of nowrap.
  • flex-wrap - Applies the flex-wrap property with the value of wrap.
  • flex-wrap-reverse - Applies the flex-wrap property with the value of wrap-reverse.
1
2
3
4
5
6
7
8
9
10
<div class="flex-nowrap">...</div>
1
2
3
4
5
6
7
8
9
10
<div class="flex-wrap">...</div>
1
2
3
4
5
6
7
8
9
10
<div class="flex-wrap-reverse">...</div>

flex-justify-[value]

Applies the justify-content property with the provided key as the value.

  • flex-justify-start
  • flex-justify-center
  • flex-justify-end
  • flex-justify-between
  • flex-justify-around
  • flex-justify-evenly
...
...
<div class="grid flex-justify-start">...</div>
...
...
<div class="grid flex-justify-center">...</div>
...
...
<div class="grid flex-justify-end">...</div>
...
...
<div class="grid flex-justify-between">...</div>

flex-align-[value]

Applies the align-items property with the provided key as the value.

  • flex-align-start
  • flex-align-center
  • flex-align-end
  • flex-align-stretch
  • flex-align-baseline
...
...
<div class="grid flex-align-start">
  <div class="grid__item" style="height: 100px;">...</div>
  <div class="grid__item">...</div>
</div>
...
...
<div class="grid flex-align-center">
  <div class="grid__item" style="height: 100px;">...</div>
  <div class="grid__item">...</div>
</div>
...
...
<div class="grid flex-align-end">
  <div class="grid__item" style="height: 100px;">...</div>
  <div class="grid__item">...</div>
</div>

flex-items-[key]

Gives all direct children the flex property to either share the container space equally (equal) or keep their content’s width (auto).

  • flex-items-equal - Applies the flex property children elements with the value of 1 1 0 to share the container space equally.
  • flex-items-auto - Applies the flex property children elements with the value of 0 0 auto to keep their content’s width.
...
...
...
<div class="flex-items-equal">...</div>
...
...
...
<div class="flex-items-auto">...</div>

flex-gap-[key]

The flex-gap module adds both horizontal and vertical spacing between an element’s children. It also adds negative top and left margins to the element it’s applied to which may require an anonymous <div> if additional margins are needed. Flex-gap keys and their values are generated from the $gap-map variable map.

  • flex-gap
  • flex-gap-[key]
...
...
...
...
...
...
...
...
...
...
<!-- Using the default gap class -->
<div class="flex-gap">...</div>

<!-- Using the gap class with variant key -->
<div class="flex-gap-none">...</div>
<div class="flex-gap-xs">...</div>
<div class="flex-gap-sm">...</div>
<div class="flex-gap-md">...</div>
<div class="flex-gap-lg">...</div>
<div class="flex-gap-xl">...</div>
Variable Default Description
$output-flex-gap $outputtrue Toggles the output of this module.
$class-flex-gap "flex-gap" String to use for the class name of the flex-gap utility.

flex-gap-x-[key]

Adds flex-gap spacing horizontally between an element’s children using margin-left. Flex-gap keys and their values are generated from the $gap-map variable map.

  • flex-gap-x
  • flex-gap-x-[key]
...
...
...
...
...
...
...
...
...
...
<!-- Using the default gap class -->
<div class="flex-gap-x">...</div>

<!-- Using the gap class with variant key -->
<div class="flex-gap-x-none">...</div>
<div class="flex-gap-x-xs">...</div>
<div class="flex-gap-x-sm">...</div>
<div class="flex-gap-x-md">...</div>
<div class="flex-gap-x-lg">...</div>
<div class="flex-gap-x-xl">...</div>
Variable Default Description
$output-flex-gap-x $outputtrue Toggles the output of this module.
$class-flex-gap-x "flex-gap-x" String to use for the class name of the flex-gap-x utility.

flex-gap-y-[key]

Adds flex-gap spacing vertically between an element’s children using margin-top. Flex-gap keys and their values are generated from the $gap-map variable map.

  • flex-gap-y
  • flex-gap-y-[key]
...
...
...
...
...
...
...
...
...
...
<!-- Using the default gap class -->
<div class="flex-gap-y">...</div>

<!-- Using the gap class with variant key -->
<div class="flex-gap-y-none">...</div>
<div class="flex-gap-y-xs">...</div>
<div class="flex-gap-y-sm">...</div>
<div class="flex-gap-y-md">...</div>
<div class="flex-gap-y-lg">...</div>
<div class="flex-gap-y-xl">...</div>
Variable Default Description
$output-flex-gap-y $outputtrue Toggles the output of this module.
$class-flex-gap-y "flex-gap-y" String to use for the class name of the flex-gap-y utility.

font

A utility for adjusting various font styles.

Variable Default Description
$output-font $outputtrue Toggles the output of this module.
$class-font "font" String to use for the class name of the font utility.
Class Example
font-family-sans

Font example...

font-family-serif

Font example...

font-family-mono

Font example...

font-size-base

Font example...

font-size-sm

Font example...

font-size-lg

Font example...

font-leading-base

Lorem ipsum dolor sit amet
consectetur adipiscing elit.

font-leading-sm

Lorem ipsum dolor sit amet
consectetur adipiscing elit.

font-leading-lg

Lorem ipsum dolor sit amet
consectetur adipiscing elit.

font-kerning-0

Font example...

font-kerning-1

Font example...

font-kerning-2

Font example...

font-weight-normal

Font example...

font-weight-medium

Font example...

font-weight-semibold

Font example...

font-weight-bold

Font example...

font-weight-lighter

Font example...

font-weight-bolder

Font example...

font-style-normal

Font example...

font-style-italic

Font example...

gap-x-[key]

Adds gap spacing horizontally using margin-left and the > * + * selector. Gap-x keys and their values are generated from the $gap-map variable map.

  • gap-x
  • gap-x-[key]
...
...
...
...
<!-- Using the default gap-x class -->
<div class="gap-x">...</div>

<!-- Using the gap-x class with variant key -->
<div class="gap-x-none">...</div>
<div class="gap-x-xs">...</div>
<div class="gap-x-sm">...</div>
<div class="gap-x-md">...</div>
<div class="gap-x-lg">...</div>
<div class="gap-x-xl">...</div>
Variable Default Description
$output-gap-x $outputtrue Toggles the output of this module.
$class-gap-x "gap-x" String to use for the class name of the gap-x utility.

gap-y-[key]

Adds gap spacing vertically using margin-top and the > * + * selector. Gap-y keys and their values are generated from the $gap-map variable map.

  • gap-y
  • gap-y-[key]
...
...
...
<!-- Using the default gap-y class -->
<div class="gap-y">...</div>

<!-- Using the gap-y class with variant key -->
<div class="gap-y-none">...</div>
<div class="gap-y-xs">...</div>
<div class="gap-y-sm">...</div>
<div class="gap-y-md">...</div>
<div class="gap-y-lg">...</div>
<div class="gap-y-xl">...</div>
Variable Default Description
$output-gap-y $outputtrue Toggles the output of this module.
$class-gap-y "gap-y" String to use for the class name of the gap-y utility.

margin

Add margin to an element using directional and size variations. Margin size and spacing values are generated from $gap-map variable map.

  • margin - Adds margins on all sides.
  • margin-[direction] - Adds default margin to a specific side.
  • margin-[size] - Adds margins on all sides with a specific size key.
  • margin-[direction]-[size] - Adds margins on a specific side and size.
  • margin-x-[size] - Adds left and right margins with a specific size key.
  • margin-y-[size] - Adds top and bottom margins with a specific size key.
  • margin-auto - Sets margins to auto.
  • margin-[direction]-auto - Sets margins auto to a specific side.
  • margin-x-auto - Sets left and right margins to auto.
  • margin-y-auto - Sets top and bottom margins to auto.
[direction]

top

right

bottom

left

x left & right

y top & bottom

[size]

none ...0

xs ...0.25em

sm ...0.5em

md ...1em

lg ...1.5em

xl ...2em

auto ...auto

Variable Default Description
$output-margin $outputtrue Toggles the output of this module.
$class-margin "margin" String to use for the class name of the margin utility.

max-width

Set the max-width property on an element using values mapped from scale keys. Scale variations are built using the $max-width-scale variable map.

  • max-width - Sets the max-width propertry to the default value set in $max-width.
  • max-width-none - Sets the max-width property to none.
  • max-width-[key] - Sets the max-width property to the value of a specific scale key.
  • max-width-full - Sets the max-width property to 100%.
Variable Default Description
$output-max-width $outputtrue Toggles the output of this module.
$class-max-width "max-width" String to use for the class name of the max-width utility.
$max-width 70rem The default value used to set max-width.
$max-width-scale Sass map ref ↓ Map used to build max-width utility variants.

$max-width-scale

A scale map used for building max-width utility variations using the key as variant name.

$max-width-scale: (
  'none': none,
  'xs': 45rem,
  'sm': 60rem,
  'md': 70rem,
  'lg': 80rem,
  'xl': 90rem,
  'full': 100%
) !default;

padding

Add padding to an element using directional and size variations. Padding size and spacing values are generated from $gap-map variable map.

  • padding - Adds default padding on all sides.
  • padding-[direction] - Adds default padding to a specific side.
  • padding-[size] - Adds padding on all sides with a specific size key.
  • padding-[direction]-[size] - Adds padding on a specific side and size.
  • padding-x-[size] - Sets left and right padding to a specific size key.
  • padding-y-[size] - Sets top and bottom padding to a specific size key.
[direction]

top

right

bottom

left

x left & right

y top & bottom

[size]

none ...0

xs ...0.25em

sm ...0.5em

md ...1em

lg ...1.5em

xl ...2em

Variable Default Description
$output-padding $outputtrue Toggles the output of this module.
$class-padding "padding" String to use for the class name of the padding utility.

text

A utility for adjusting various text styles.

Variable Default Description
$output-text $outputtrue Toggles the output of this module.
$class-text "text" String to use for the class name of the text utility.
Class Example
text-capitalize

Text example...

text-lowercase

Text example...

text-uppercase

Text example...

text-align-left

Text example...

text-align-center

Text example...

text-align-right

Text example...

text-strike

Text example...

text-underline

Text example...

text-underline-dotted

Text example...

text-underline-dashed

Text example...

text-wrap

Text example...

text-nowrap

Text example...

text-overflow-ellipsis

Adds ellipsis styles to an element that will display an ellipsis (…) for text that would otherwise wrap.

Text example: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum laoreet interdum elit, non blandit arcu luctus quis. Duis mattis et massa a congue.
<div class="text-overflow-ellipsis">...<div>