Appearance
Functions
Sass functions: colors, units, lookups in the tokens.
26 documented in src/functions.scss.
theme($token)
Returns a CSS custom property reference for a semantic theme token. Companion to mx.generate-theme() - use this to reference tokens in your SCSS.
| Parameter | Type | Description |
|---|---|---|
$token | string | The semantic token name (e.g., 'primary', 'on-surface'). |
Returns A CSS var() reference, e.g. var(--primary).
get-color($color-name, $variant: 'default')
Retrieves a color value from the $colors Material palette map. Shorthand to avoid nested map.get() calls.
| Parameter | Type | Description |
|---|---|---|
$color-name | string | The color family name (e.g., 'red', 'blue-grey', 'white'). |
$variant | string | The color variant (e.g., 'default', 'darken-2', 'accent-1'). Default: 'default'. |
Returns The hex color value.
Throws Error if the color name or variant does not exist.
strip-unit($value)
Removes the unit from a numeric value.
| Parameter | Type | Description |
|---|---|---|
$value | number | The value to process. |
Returns The unitless value.
calc-rem($value, $base-font-size, $force-zero-rem: false)
Converts a single pixel value to rem units with unit validation.
| Parameter | Type | Description |
|---|---|---|
$value | number|string | The pixel value to convert. |
$base-font-size | number | The base font size used for conversion. |
$force-zero-rem | boolean | (optional, default: false) - If true, outputs 0rem for zero values. |
Returns The rem value or the original value if invalid.
length-to-rem($value)
Converts a length in px to rem and leaves the rest as it is: a keyword (normal), a percentage (100%), a unitless number. For the properties that take both, like letter-spacing.
| Parameter | Type | Description |
|---|---|---|
$value | number|string | The pixel value, or the keyword. |
Returns The value in rem, or the keyword.
px-to-rem($px, $options: ())
Converts one or multiple pixel values to rem units.
| Parameter | Type | Description |
|---|---|---|
$px | number|list<number> | The pixel value(s) to convert. |
$options | map|null | (optional) - A map of options: |
Returns The rem value(s).
Throws Error if the input is not a number or list of numbers.
corners-cut-symmetry($corners, $symmetry)
Applies symmetry to corner values in a map. This function allows you to apply symmetry to corner values in a map. Depending on the selected symmetry type ('horizontal', 'vertical', or 'diagonal'), the function will mirror corner values across the designated axis.
| Parameter | Type | Description |
|---|---|---|
$corners | map | A map of corner values (e.g., 'top-left', 'bottom-right'). |
$symmetry | string | The type of symmetry to apply ('horizontal', 'vertical', 'diagonal'). |
Returns A new map with symmetrical corner values.
Throws Error if the specified symmetry type is invalid.
get-elevation-value($level, $key, $property)
Retrieves a value from the elevation map. This function allows you to retrieve a specific property from a map that holds elevation levels (e.g., 'low', 'medium'). You can retrieve properties such as box-shadow, offset-x, etc., based on the provided level, key, and property.
| Parameter | Type | Description |
|---|---|---|
$level | string | The elevation level (e.g., 'low', 'medium'). |
$key | string | The specific shadow key (e.g., 'box-shadow'). |
$property | string | The property to retrieve (e.g., 'offset-x'). |
Returns The value associated with the specified property.
Throws Error if the level, key, or property does not exist.
color-tone-of($color)
How light a color looks to the eye, from 0 (black) to 100 (white): the L* of CIELAB, the measure that the tones of Material 3 are made on. Two colors with the same tone have the same contrast against black and white, whatever their hue.
| Parameter | Type | Description |
|---|---|---|
$color | color | The color. |
Returns Its tone, from 0 to 100.
color-tone($color, $tone)
The color of a tone: the hue and the chroma (how vivid) of $color, at the tone asked, from 0 (black) to 100 (white). It is how Material 3 builds its roles from one color: a container is tone 90, the text on it tone 10. The tone is exact (CIELAB L*). Material works on the hue and the chroma of HCT, close to the ones of CIELCH used here, so the colors are close to Material's but not always identical (the baseline purple at tone 90 is #ecdfff, Material has #eaddff). A color that cannot be shown at that tone and chroma gets the nearest one that can.
| Parameter | Type | Description |
|---|---|---|
$color | color | The color that gives the hue and the chroma. |
$tone | number | The tone, from 0 to 100. |
Returns The color of that tone.
Throws Error if the tone is not between 0 and 100.
get-motion($name, $property)
A value of $motion, ready to write: a key of $durations or $easings becomes its value.
| Parameter | Type | Description |
|---|---|---|
$name | string | The kind of movement (enter, exit, enter-small, state...). |
$property | string | duration or easing. |
Returns The time or the curve.
Throws Error if the movement or the property does not exist.
elevation-shadow($level, $color: null)
The box-shadow of an elevation level: its two layers of shadow, in rem.
| Parameter | Type | Description |
|---|---|---|
$level | number | The level (0 to 5). |
$color | color|null | The color of the shadow. Default: the color of each layer in $elevations. |
Returns The shadow, to use as the value of box-shadow or of a custom property.
Throws Error if the level does not exist.
color-legibility($background, $dark, $light, $threshold: 50)
Determines the most readable color based on background lightness. This function helps determine whether to use a dark or light text color based on the lightness of the provided background color. The goal is to ensure better readability and contrast for text displayed over different background colors.
| Parameter | Type | Description |
|---|---|---|
$background | color | The background color to evaluate. |
$dark | color | The dark color to use for light backgrounds. |
$light | color | The light color to use for dark backgrounds. |
$threshold | number | The lightness (0 to 100) above which a background counts as light. Defaults to 50. |
Returns The chosen color (dark or light) for better readability.
breakpoint-min($key)
The width from which a width class starts.
| Parameter | Type | Description |
|---|---|---|
$key | string | The width class (medium...). |
Returns The minimum width, in px.
Throws Error if the class does not exist.
breakpoint-max($key)
The width up to which a width class goes: one pixel before the next class starts.
| Parameter | Type | Description |
|---|---|---|
$key | string | The width class. |
Returns The maximum width, in px, or null for the last class.
Throws Error if the class does not exist.
get-container($key)
Retrieves a container width from the map.
| Parameter | Type | Description |
|---|---|---|
$key | string | The width class (medium, or base...). |
Returns The maximum width in rem, or 100% for base.
Throws Error if the container is not found.
get-grid($key, $property)
Retrieves a grid property value from the map.
| Parameter | Type | Description |
|---|---|---|
$key | string | The width class (base, medium, expanded). |
$property | string | cols, gap or margin. |
Returns The value, in rem for gap and margin.
Throws Error if the class or the property is not found.
get-type($role, $property)
Retrieves a property of a style of the type scale, ready to write: sizes, line heights and tracking in rem, and the weight as a number.
| Parameter | Type | Description |
|---|---|---|
$role | string | The style (body-medium, headline-large...). |
$property | string | size, line-height, tracking, weight, emphasized-weight or font. |
Returns The value.
Throws Error if the style or the property is not found.
get-heading($level, $property)
Retrieves a heading property value from the map. The text properties (line-height, spacing, weight) come from the style of the type scale that the heading uses (role).
| Parameter | Type | Description |
|---|---|---|
$level | string | The heading level (1 to 6). |
$property | string | margin, padding, role, line-height, spacing or weight. |
Returns The value of the requested heading property.
Throws Error if the heading level or property is not found.
get-spacing($key, $as-px: false)
Retrieves a spacing value from the map and converts it to rem. This function retrieves a spacing value based on the provided key (e.g., 'small', 'medium') and converts it to rem if necessary. It provides flexibility by allowing an option to return the value in pixels.
| Parameter | Type | Description |
|---|---|---|
$key | string | The spacing key (e.g., 'small', 'medium'). |
$as-px | boolean | Optional flag to return value in pixels (defaults to false). |
Returns The rem value of the spacing.
Throws Error if the spacing key is not found.
get-line-height($key)
Retrieves a line-height value from the map. This function retrieves a line-height value based on the provided key (e.g., 'small', 'medium'). The value is returned as stored: a ratio without unit, or a length in px that the caller converts with px-to-rem().
| Parameter | Type | Description |
|---|---|---|
$key | string | The line-height key (e.g., 'small', 'medium'). |
Returns The line-height value.
Throws Error if the line-height key is not found.
get-value-from-map($map, $keys...)
Retrieves a nested value from a map using a list of keys. This function allows you to traverse through a nested map using a list of keys. It validates the existence of each key and returns the final value found at the specified location.
| Parameter | Type | Description |
|---|---|---|
$map | map | The map to search in. |
$keys | list<string> | The list of keys to traverse. |
Returns The value at the nested map location.
Throws Error if any of the keys is not found in the map.
ratio($width, $height)
Calculates the aspect ratio as a percentage. This function calculates the aspect ratio of a given width and height as a percentage of the width.
| Parameter | Type | Description |
|---|---|---|
$width | number | The width value in pixels. |
$height | number | The height value in pixels. |
Returns The aspect ratio as a percentage value.
color-rgb($color, $as-rgb: true)
Applies transparency to a color by setting its alpha value. This function reduces the opacity of the given color based on a specified opacity level and can return the color in RGB format or as a list of values.
| Parameter | Type | Description |
|---|---|---|
$color | color | The color to modify. |
$as-rgb | boolean | If true, the color is returned in RGB format. Defaults to true, meaning the color will be returned as rgb(red green blue). |
Returns The color with transparency applied in either rgb format or as a list of red, green, and blue channels.
color-alpha($color, $opacity: 50%)
Applies transparency to a color by setting its alpha value. This function applies the specified opacity level to the given color, and returns the color in RGBA format.
| Parameter | Type | Description |
|---|---|---|
$color | color | The color to modify. |
$opacity | number | The desired opacity level: a ratio from 0 (fully transparent) to 1 (fully opaque), or a percentage from 0% to 100%. Defaults to 50%. |
Returns The color with the specified alpha value applied in RGBA format.
calculate-fluid-font($min, $fluid-size, $max)
Calculates the fluid font size based on the viewport width using the clamp() function. This function dynamically calculates a fluid font size based on the viewport width and ensures that the font size never falls below the minimum or exceeds the maximum.
| Parameter | Type | Description |
|---|---|---|
$min | Number | The minimum font size in pixels, used to limit the scaling of the font size. |
$fluid-size | Number | The viewport width (in vw) at which the font size will be based. |
$max | Number | The maximum font size in pixels, used to limit the scaling of the font size. |
Returns A string representing the fluid font size using the clamp() function, which can be used directly in the CSS style.