@xenyo/sass-utils
General-purpose Sass utils for Xenyo web development projects.
Installation
npm i @xenyo/sass-utils
Usage
Create sass-utils/_index.scss
in your project root with the following contents:
@forward '@xenyo/sass-utils';
// Add custom variables or mixins here
// DO NOT output any CSS, doing so will cause unnecessary duplication
Then, add this to the top of your scss files:
@use 'sass-utils' as *;
Alternatively, if you don't need to add any customizations, just use this:
@use '@xenyo/sass-utils' as *;
The sass-utils/_index.scss
won't be needed in this case.
Tests
All utilites are unit tested with True.
Run tests:
npm test
Watch files for changes:
npm run watch
API Reference
animate
animate()
Adds a keyframe animation with a unique, randomly-generated animation name.
// Source
.my-element {
@include animate {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
}
// Output
.my-element {
animation: animate-u09hl8n var(--animation-duration) var(--animation-timing-function);
}
@keyframes animate-u09hl8n {
from {
opacity: 0;
}
to {
opacity: 1;
}
}
Custom properties
Property | Default | Description |
---|---|---|
--animation-duration |
0.3s | The animation duration. |
--animation-timing-function |
ease-out | The animation timing function. |
full-width
full-width()
Forces an element to be the width of the browser window.
// Source
.my-element {
@include full-width;
}
// Output
.my-element {
width: 100vw;
position: relative;
left: 50%;
right: 50%;
margin-left: -50vw;
margin-right: -50vw;
}
See https://css-tricks.com/full-width-containers-limited-width-parents/
This method ignores the width of the vertical scrollbar, which can lead to unexpected results.
hide-text
hide-text()
Hides the text inside an element without affecting any other child elements.
// Source
.my-element {
@include hide-text();
}
// Output
.my-element {
text-indent: 200%;
white-space: nowrap;
overflow: hidden;
}
See https://stackoverflow.com/questions/471510/hide-text-using-css
line-clamp
line-clamp($lines: 1)
Clamps the text inside an element to N lines.
// Source
.my-element {
@include line-clamp(3);
}
// Output
.my-element {
display: -webkit-box;
-webkit-line-clamp: 3;
-webkit-box-orient: vertical;
overflow: hidden;
}
See https://css-tricks.com/line-clampin/
media
below($max-width)
Outputs a media query that applies styles for viewports less than the given width.
// Source
$lg: 1500px;
.my-element {
@include below($lg) {
display: none;
}
}
// Output
@media (max-width: 1499.98px) {
.my-element {
display: none;
}
}
above($min-width)
Outputs a media query that applies styles for viewports greater than or equal to the given width.
// Source
$lg: 1500px;
.my-element {
@include above($lg) {
display: none;
}
}
// Output
@media (min-width: 1500px) {
.my-element {
display: none;
}
}
between($min-width, $max-width)
Outputs a media query that applies styles for viewports between the given widths, including $min-width
and excluding $max-width
.
// Source
$md: 1000px;
$lg: 1500px;
.my-element {
@include between($md, $lg) {
display: none;
}
}
// Output
@media (min-width: 1000px) and (max-width: 1499.98px) {
.my-element {
display: none;
}
}
transition
transition($properties: all)
Applies a transition to the given property names.
// Source
.my-element {
@include transition;
}
// Output
.my-element {
transition: all var(--transition-duration) var(--transition-timing-function);
}
Pass a single property name:
// Source
.my-element {
@include transition(opacity);
}
// Output
.my-element {
transition: opacity var(--transition-duration) var(--transition-timing-function);
}
Pass multiple propery names:
// Source
.my-element {
@include transition(opacity transform);
}
// Output
.my-element {
transition: opacity var(--transition-duration) var(--transition-timing-function), transform var(--transition-duration) var(--transition-timing-function);
}
Custom properties
Property | Default | Description |
---|---|---|
--transition-duration |
0.3s | The transition duration. |
--transition-timing-function |
ease-out | The transition timing function. |
trim-margin
trim-margin($directions: top bottom)
Trims the margins of first-child and last-child elements.
// Source
.my-element {
margin: 10px;
@include trim-margin;
}
// Output
.my-element {
margin: 10px;
}
.my-element:first-child {
margin-top: 0;
}
.my-element:last-child {
margin-bottom: 0;
}
Pass any combination of top
, bottom
, left
and right
to trim in those
directions only:
// Source
.my-element {
margin: 10px;
@include trim-margin(left right);
}
// Output
.my-element {
margin: 10px;
}
.my-element:first-child {
margin-left: 0;
}
.my-element:last-child {
margin-right: 0;
}