css-utility-functions

CSS Utility Functions

A collection of reusable CSS custom native functions using the new @function syntax.

⚠️ Experimental Feature: CSS @function is currently experimental. Check browser compatibility before using in production.

Installation

npm install css-utility-functions

Or download and include in your project.

Usage

Option 1: Use Bundled Version (Recommended)

/* All functions in one file */
@import 'css-utility-functions';

/* Or use minified version */
@import 'css-utility-functions/dist/index.min.css';

Option 2: Import Individual Functions

@import 'css-utility-functions/src/alpha.css';
@import 'css-utility-functions/src/fluid.css';
/* ... import only what you need */

Option 3: Development (Source Files)

@import './src/index.css';

Building

# Install dependencies
npm install

# Build bundled version
npm run build

# Build minified version
npm run build:min

# Build both
npm run build:all

# Watch for changes
npm run watch

Available Functions

Color Utilities

--alpha()

Creates a semi-transparent version of any color.

.overlay {
  background: --alpha(#6366f1, 0.2);
}

--lighten() / --darken()

Adjust a color's lightness. Use decimal values (0.1 = 10%, 0.2 = 20%).

.btn:hover {
  background: --lighten(var(--btn-bg), 0.15);
}

--saturate() / --desaturate()

Adjust a color's saturation/chroma. Use decimal values (0.4 = 40%, 1.0 = 100%).

.vibrant {
  background: --saturate(var(--primary), 0.4);
}

--mix()

Blend two colors by percentage.

.tinted {
  background: --mix(white, var(--brand), 90%);
}

--contrast-text()

Auto-select black or white text for optimal contrast.

.badge {
  background: var(--badge-color);
  color: --contrast-text(var(--badge-color));
}

Spacing & Sizing

--space()

Consistent spacing scale (4px base).

.card {
  padding: --space(4);        /* 1rem */
  gap: --space(2);            /* 0.5rem */
}

--fluid()

Responsive sizing that scales smoothly between viewports.

h1 {
  font-size: --fluid(1.5rem, 4rem);
}

--ratio-height()

Calculate height from width and aspect ratio.

.video-thumb {
  width: 320px;
  height: --ratio-height(320px, 16, 9);  /* 180px */
}

Visual Effects

--shadow()

Elevation shadows based on level (1-5). Optionally control shadow direction with angle parameter.

.card {
  box-shadow: --shadow(2);
}

.lit-from-top-right {
  box-shadow: --shadow(3, oklch(0% 0 0 / 0.15), 135deg);
}

.lit-from-left {
  box-shadow: --shadow(2, oklch(0% 0 0 / 0.1), 180deg);
}

--bevel()

Inset elevation shadows for embossed/debossed effects. Optionally control light source direction with angle parameter.

.pressed-button {
  box-shadow: --bevel(2);
}

.lit-from-top {
  box-shadow: --bevel(2, oklch(0% 0 0 / 0.1), 270deg);
}

.input-field {
  box-shadow: --bevel(1, oklch(0% 0 0 / 0.08), 90deg);
}

Layout Utilities

--neg()

Negate a value (useful for negative margins).

.pull-up {
  margin-top: --neg(var(--header-height));
}

Unit Conversion

--to-rem() / --to-px()

Convert between pixels and rem (assumes 16px base).

.legacy {
  font-size: --to-rem(18);    /* 1.125rem */
  width: --to-px(10);         /* 160px */
}

Quick Reference

Function	Purpose	Example
Color Utilities
--alpha()	Color transparency	--alpha(blue, 0.3)
--lighten()	Increase lightness	--lighten(#333, 0.2)
--darken()	Decrease lightness	--darken(#ccc, 0.1)
--saturate()	Boost saturation	--saturate(gray, 0.5)
--desaturate()	Reduce saturation	--desaturate(#f00, 0.3)
--mix()	Blend colors	--mix(red, blue, 25%)
--contrast-text()	Auto text color	--contrast-text(var(--bg))
--grayscale()	Remove saturation	--grayscale(#6366f1)
--invert()	Invert lightness	--invert(#fff) → #000
--complement()	Complementary color	--complement(blue) → orange
Spacing & Sizing
--space()	Spacing scale	--space(4) → 1rem
--fluid()	Viewport-responsive sizing	--fluid(1rem, 3rem)
--fluid-container()	Container-responsive sizing	--fluid-container(1rem, 2rem)
--ratio-height()	Aspect ratio calc	--ratio-height(100px, 16, 9)
Visual Effects
--shadow()	Elevation shadows	--shadow(3)
--bevel()	Inset shadows (emboss/deboss)	--bevel(2)
--diagonal-lines()	Diagonal line pattern	--diagonal-lines(--angle: 45deg)
Layout Utilities
--neg()	Negate value	--neg(2rem) → -2rem
Math Utilities
--lerp()	Linear interpolation	--lerp(100px, 500px, 0.5)
--circle-x() / --circle-y()	Circle coordinates	--circle-x(100px, 45deg)
--modular()	Typographic scale	--modular(2, 1rem, 1.25)
--poly-angle()	Polygon vertex angle	--poly-angle(6, 0)
Unit Conversion
--to-rem()	px → rem	--to-rem(16) → 1rem
--to-px()	rem → px	--to-px(2) → 32px
Logic Operations
--not()	Boolean negation	--not(1) → 0
--and()	Logical AND	--and(1, 1) → 1
--or()	Logical OR	--or(0, 1) → 1
--xor()	Exclusive OR	--xor(1, 0) → 1
--nand()	NOT AND	--nand(1, 1) → 0
--nor()	NOT OR	--nor(0, 0) → 1
--xnor()	Exclusive NOR	--xnor(1, 1) → 1

Browser Support

CSS @function is an experimental feature. Check MDN for current browser support.

License

MIT (or your preferred license)