@felix_berlin/sass-butler

SASS Butler

Stands by your side with plenty of features and mixins.

SASS Butler is a big collection of SASS mixins and functions.

Mixins and functions are unit tested via Jest and True. Unfortunately, it is not yet possible to create a coverage report.

Whats inside?

Visit https://sass-butler.kasimir.dev for full documentation.

Functions

• colors
  • hex-to-rgb-values()
  • hex-to-rgb()
• converters
  • px-to-rem()
• lists
  • first-of-list()
  • last-of-list()
• maps
  • map-collect()
• numbers
  • strip-unit()
  • number-invert()
  • random-num()
• strings
  • str-starts-with()
  • str-ends-with()
  • str-contains()
  • str-replace()
  • escape-svg()
• typechecking
  • is-number()
  • is-time()
  • is-duration()
  • is-angle()
  • is-frequency()
  • is-integer()
  • relative-length()
  • absolute-length()
  • is-percentage()
  • is-length()
  • is-resolution()
  • is-position()

Mixins

• basic
  • select-style()
  • target-anchor-offset()
• @media
  • breakpoint()
  • dark-mode-class()
  • feature()
  • hover
• element
  • line-on-sides()
  • overlay()
  • list-style-image()
• typo
  • font-smoothing()
  • fluid-typo()
  • icon-font()
  • font-face()

Installation

pnpm add @felix_berlin/sass-butler

npm i @felix_berlin/sass-butler

yarn add @felix_berlin/sass-butler

If you haven't already, install Sass.

pnpm add -D sass

npm i -D sass

yarn add -D sass

Requirements

This project uses the "new" Sass Module system. Therefore your build tool or taskrunner have to support Dart Sass 1.79.0 or above.

Sass support

Sass Compiler	Support
Dart Sass	✅
Lib Sass	❌
Ruby Sass	⚰️

Version support

Your Dart Sass Version must be: >= 1.33.0

Usage

Import all at once or all individually

Single import of the used functionalities.

@use './node_modules/sass-butler/functions/first-of-list' as fol;

import all functions at once:

@use './node_modules/sass-butler/functions' as fn;

How to import

@use './node_modules/sass-butler/mixis/breakpoint' as breakpoint;

With sass-loader:

@use '~sass-butler/mixis/breakpoint' as breakpoint;

With webpack mix:

  .sass('resources/assets/styles/app.scss', 'styles', {
    sassOptions: {
      includePaths: ['./node_modules'],
    },
  })

@use 'sass-butler/mixis/breakpoint' as breakpoint;

Override module config

Some of the module comes with "global" config vars and maps (breakpoint mixin). This may be a problem since you can only overwrite once with with(). Here is an example how you can deal with it.

Redefine mixin or function default configs

Example how to use the breakpoint mixin with own default config:

Create a new file and load the breakpoint mixin from the node_modules with the @forward function. Similar to the @use function you can overwrite predefined vars with with().

// _custom-breakpoints.scss

@forward 'sass-butler/mixins/breakpoint' with (
  // Add your own breakpoints map
  $breakpoints: (
    'xxs': 375px,
    'xs': 568px,
    'sm': 768px,
    'md': 1024px,
    'lg': 1260px,
    'xlg': 1440px,
    'fhd': 1920px,
    'uhd': 2560px
  )
);

In the rest of your project you don't add the module via node_modules anymore but load the customized module _external.scss with @use.

// _my-module.scss

@use 'custom-breakpoints' as break;

.my-selector {
  @include break.breakpoint(lg) {
    padding: 12px 0 1rem 0;
  }
}

:warning: Pay attention to the loading order when using redefined and package function/mixins!

:x: Can't be compiled because the (package) breakpoint mixin is already loaded in mixins.scss.

@use 'sass-butler/mixins' as mx;
@use 'custom-breakpoints' as break;

:white_check_mark: This will work. Make sure to load the redefined module first.

@use 'custom-breakpoints' as break;
@use 'sass-butler/mixins' as mx;

Documentation

You can find the documentation at: https://sass-butler.kasimir.dev

The documentation is updated automatically with each commit on the master branch.

Build the docs locally

Run following command: npm run sassDoc

Contributors

Changelog

3.1.0 (2024-12-13)

Features

• upgrade to new sass colors functions (b624ef8)