Functions

Public functions exported by @nuvoui/core: tokens, colours, breakpoints, maths, strings and units. Call them in your own SCSS, such as color: token(text-muted).

This page is generated from the doc blocks in the core source when the site is built, so it always matches the current release of @nuvoui/core. Every example is compiled against core during the build; open Compiled CSS under an example to see its output. The A to Z index lists every public mixin and function.

Breakpoints

functions/_breakpoints.scss

get-breakpoint-value()

`get-breakpoint-value()` function

Resolves a breakpoint name from $breakpoints to its width; a length passes through, and a unitless number that is not a breakpoint name or an unknown name raises an error.

@function get-breakpoint-value($bp, $debug: false)

Parameter	Type	Default	Description
`$bp`	`String\|Number`	Required	Breakpoint name (xs, sm, md, lg, xl, 2xl; quoting 2xl is optional) or a length such as 800px
`$debug`	`Boolean`	`false`	Unused

Returns: Number The breakpoint width

Example

.sidebar {
  max-width: get-breakpoint-value(md);
}

Compiled CSS

.sidebar {
  max-width: 768px;
}

Source: functions/_breakpoints.scss:17

Color scale

functions/_color-scale.scss

create-color-scale()

`create-color-scale()` function

Returns the OKLCH shade scale (50 to 950) of a colour value, precomputed for the default role and palette colours and generated for any other; the value is shaded directly and never re-read as a palette name, so "blue" is CSS blue.

@function create-color-scale($color)

Parameter	Type	Default	Description
`$color`	`Color\|String`	Required	Colour value or colour string (#007bff, blue, rgb())

Returns: Map Stop to colour map with keys 50, 100 to 900 and 950

Example

@use "sass:map";
$teal: create-color-scale(#1ab5a5);
.card {
  background: map.get($teal, 100);
  border-color: map.get($teal, 600);
}

Compiled CSS

.card {
  background: #ccf7f0;
  border-color: #009e8f;
}

Source: functions/_color-scale.scss:120

Colors

functions/_colors.scss

get-color()

`get-color()` function

Returns a real colour value for Sass maths from a role, palette name or colour value at a shade stop; role and palette names win over CSS named colours, and var() or an invalid stop raises an error.

@function get-color($color, $shade: 500)

Parameter	Type	Default	Description
`$color`	`String\|Color`	Required	Role (brand, danger), palette hue (red, blue, gray) or colour value
`$shade`	`Number`	`500`	Shade stop: 50, 100 to 900, or 950

Returns: Color The shaded colour (not a var() reference, so it does not follow the theme)

Example

.chart-bar {
  background: get-color(brand, 600);
  border-color: rgba(get-color(red, 700), 0.4);
}

Compiled CSS

.chart-bar {
  background: #006be0;
  border-color: rgba(184, 24, 34, 0.4);
}

Source: functions/_colors.scss:60

Contrast

functions/_contrast.scss

find-text-color()

`find-text-color()` function

Picks whichever of two text colours has the higher WCAG contrast against the background, by default the light theme text-regular and text-inverted; a transparent background raises an error.

@function find-text-color($background, $text-colors: null)

Parameter	Type	Default	Description
`$background`	`Color`	Required	Opaque background colour
`$text-colors`	`List\|Null`	`null`	Two opaque candidate text colours; null uses the light theme text-regular and text-inverted

Returns: Color The text colour with the higher contrast ratio (the first one on a tie)

Example 1

.badge {
  background: get-color(brand, 700);
  color: find-text-color(get-color(brand, 700));
}

Compiled CSS

.badge {
  background: #0058bb;
  color: #f1f1f1;
}

Example 2

.chip {
  color: find-text-color(#0b1f3a, (#111, #fafafa));
}

Compiled CSS

.chip {
  color: #fafafa;
}

Source: functions/_contrast.scss:99

Css vars

functions/_css-vars.scss

is-css-var() get-css-var()

`is-css-var()` function

Whether a value is a var() reference.

@function is-css-var($value)

Parameter	Type	Default	Description
`$value`	`Any`	Required	Value to test

Returns: Boolean True when the value is a string starting with var(

Example

$value: var(--nu-space-4);
.card {
  @if is-css-var($value) {
    padding: $value;
  }
}

Compiled CSS

.card {
  padding: var(--nu-space-4);
}

Source: functions/_css-vars.scss:24

`get-css-var()` function

Normalises a var() reference given as a string (quoted or not) into a var() value; any other value raises an error.

@function get-css-var($value)

Parameter	Type	Default	Description
`$value`	`String`	Required	A var() reference

Returns: String The var() value

Example

.card {
  padding: get-css-var("var(--nu-space-4)");
}

Compiled CSS

.card {
  padding: var(--nu-space-4);
}

Source: functions/_css-vars.scss:54

Feature flags

functions/_feature-flags.scss

feature-enabled()

`feature-enabled()` function

Whether utility classes for a feature are generated: requires $generate-utility-classes and a feature flag that is on (a feature missing from $feature-flags counts as on).

@function feature-enabled($feature)

Parameter	Type	Default	Description
`$feature`	`String`	Required	Feature flag name (position, spacing, theme, ...)

Returns: Boolean True when the feature's utility classes are generated

Example

@if feature-enabled("position") {
  .pinned {
    @include sticky;
  }
}

Source: functions/_feature-flags.scss:23

Math

functions/_math.scss

to-number-raw() to-number()

`to-number-raw()` function

Parses the leading number of a string and returns it with the remaining text; a string that does not start with a number gives null.

@function to-number-raw($value)

Parameter	Type	Default	Description
`$value`	`Number\|String`	Required	Number or string to parse

Returns: List|Null A (number, rest) pair, for example (12, "px")

Example

@use "sass:list";
$parsed: to-number-raw("12px");
.card {
  z-index: list.nth($parsed, 1);
}

Compiled CSS

.card {
  z-index: 12;
}

Source: functions/_math.scss:99

`to-number()` function

Converts a string to a number, keeping a trailing CSS unit as a real unit ("12px" gives 12px) or applying $append-unit; other trailing text is dropped and a non-numeric string gives null.

@function to-number($value, $append-unit: null)

Parameter	Type	Default	Description
`$value`	`Number\|String`	Required	Number or string to convert
`$append-unit`	`String\|Number`	`null`	Unit name or unit number (rem, 1rem) applied to the parsed number, replacing any trailing text

Returns: Number|Null The number, or null when the string is not numeric

Example

.card {
  width: to-number("12px");
  height: to-number("8", 1rem);
}

Compiled CSS

.card {
  width: 12px;
  height: 8rem;
}

Source: functions/_math.scss:171

Strings

functions/_strings.scss

str-replace() strip-quotes() str-trim() split()

`str-replace()` function

Replaces every occurrence of $search in $string.

@function str-replace($string, $search, $replace: " ")

Parameter	Type	Default	Description
`$string`	`String`	Required	Source string
`$search`	`String`	Required	Substring to find
`$replace`	`String`	`" "`	Replacement string

Returns: String The string with all occurrences replaced

Example

.icon::before {
  content: str-replace("arrow_left", "_", "-");
}

Compiled CSS

.icon::before {
  content: "arrow-left";
}

Source: functions/_strings.scss:17

`strip-quotes()` function

Removes one pair of matching single or double quote characters around a string; other values pass through.

@function strip-quotes($string)

Parameter	Type	Default	Description
`$string`	`Any`	Required	Value to unquote

Returns: Any The string without its surrounding quote characters

Example

.label::after {
  content: strip-quotes("'new'");
}

Compiled CSS

.label::after {
  content: "new";
}

Source: functions/_strings.scss:33

`str-trim()` function

Removes leading and trailing spaces from a string.

@function str-trim($string)

Parameter	Type	Default	Description
`$string`	`String`	Required	String to trim

Returns: String The trimmed string

Example

.label::after {
  content: str-trim("  new  ");
}

Compiled CSS

.label::after {
  content: "new";
}

Source: functions/_strings.scss:53

`split()` function

Splits a string on a delimiter, ignoring delimiters inside parentheses, and trims each part.

@function split($string, $delimiter)

Parameter	Type	Default	Description
`$string`	`String`	Required	String to split
`$delimiter`	`String`	Required	Single character delimiter

Returns: List Comma separated list of unquoted parts

Example

@use "sass:list";
$parts: split("1rem, rgb(0, 0, 0), md", ",");
.card {
  padding: list.nth($parts, 1);
}

Compiled CSS

.card {
  padding: 1rem;
}

Source: functions/_strings.scss:76

Tokens

functions/_tokens.scss

token()

`token()` function

Returns the var() reference of a v2 token; an unknown name, a --nu- prefixed name or a disabled theme feature raises an error.

@function token($name)

Parameter	Type	Default	Description
`$name`	`String`	Required	Token name without the --nu- prefix (brand, text-muted, space-4)

Returns: String var(--nu-{name}), with no fallback value

Example

.card {
  color: token(text-muted);
  background: token(bg-surface);
  padding: token(space-4);
}

Compiled CSS

.card {
  color: var(--nu-text-muted);
  background: var(--nu-bg-surface);
  padding: var(--nu-space-4);
}

Source: functions/_tokens.scss:292

Types

functions/_types.scss

get-type()

`get-type()` function

Classifies a value as null, color, number, boolean, list, map, css-var, state, breakpoint, font-weight, border-radius, css-keyword, css-function or string.

@function get-type($value)

Parameter	Type	Default	Description
`$value`	`Any`	Required	Value to classify

Returns: String The type name

Example

.card {
  @if get-type("var(--nu-space-4)") == "css-var" {
    padding: var(--nu-space-4);
  }
}

Compiled CSS

.card {
  padding: var(--nu-space-4);
}

Source: functions/_types.scss:27

Units

functions/_units.scss

strip-unit() safe-unit-name() fix-units()

`strip-unit()` function

Removes the unit from a number; a non-number raises an error.

@function strip-unit($value)

Parameter	Type	Default	Description
`$value`	`Number`	Required	Number with or without a unit

Returns: Number The unitless number

Example

.card {
  line-height: strip-unit(24px) * 0.1;
}

Compiled CSS

.card {
  line-height: 2.4;
}

Source: functions/_units.scss:19

`safe-unit-name()` function

Converts a unit to a string that is safe in an identifier (% gives per, . gives dot); used to build unique keyframe names.

@function safe-unit-name($unit)

Parameter	Type	Default	Description
`$unit`	`String`	Required	Unit string

Returns: String The identifier safe unit name

Example

@keyframes slide-#{safe-unit-name("%")} {
  to {
    opacity: 1;
  }
}

Compiled CSS

@keyframes slide-per {
  to {
    opacity: 1;
  }
}

Source: functions/_units.scss:36

`fix-units()` function

Adds a unit to a unitless number or numeric string; values with a unit, CSS keywords and null pass through, and other types raise an error.

@function fix-units($val, $unit: config-flags.$default-unit, $debug: null)

Parameter	Type	Default	Description
`$val`	`Number\|String`	Required	Value to check
`$unit`	`String`	`config-flags.$default-unit`	Unit to add ($default-unit, rem by default)
`$debug`	`Any`	`null`	Unused

Returns: Number|String The value with a unit

Example

.card {
  width: fix-units(20);
  height: fix-units("10", px);
}

Compiled CSS

.card {
  width: 20rem;
  height: 10px;
}

Source: functions/_units.scss:57

Borders

utilities/_borders.scss

get-rounded-value()

`get-rounded-value()` function

Resolves a border radius: a $border-radii key gives its token, null gives the md token, and values with units stay raw.

@function get-rounded-value($val, $label: "get-rounded-value")

Parameter	Type	Default	Description
`$val`	`String\|Length\|Null`	Required	A $border-radii key (xs, sm, md, lg, xl, 2xl, full, none), a length, calc(), var() or null
`$label`	`String`	`"get-rounded-value"`	Name that starts error messages; the rounded mixins pass their own name

Returns: String|Length A var(--nu-radius-*) reference or the raw value

Example

.card {
  border-radius: get-rounded-value(lg); // var(--nu-radius-lg)
}

Compiled CSS

.card {
  border-radius: var(--nu-radius-lg);
}

Note. A unitless number that is not a key, such as 4, raises an error.

See also: rounded. Source: utilities/_borders.scss:75

Functions

Breakpoints

get-breakpoint-value() function

Color scale

create-color-scale() function

Colors

get-color() function

Contrast

find-text-color() function

Css vars

is-css-var() function

get-css-var() function

Feature flags

feature-enabled() function

Math

to-number-raw() function

to-number() function

Strings

str-replace() function

strip-quotes() function

str-trim() function

split() function

Tokens

token() function

Types

get-type() function

Units

strip-unit() function

safe-unit-name() function

fix-units() function

Borders

get-rounded-value() function

`get-breakpoint-value()` function

`create-color-scale()` function

`get-color()` function

`find-text-color()` function

`is-css-var()` function

`get-css-var()` function

`feature-enabled()` function

`to-number-raw()` function

`to-number()` function

`str-replace()` function

`strip-quotes()` function

`str-trim()` function

`split()` function

`token()` function

`get-type()` function

`strip-unit()` function

`safe-unit-name()` function

`fix-units()` function

`get-rounded-value()` function