Sass Functions

Behind the scenes, Foundation is powered by a set of utility Sass functions that help us work with colors, units, selectors, and more.

Importing

All of Foundation's Sass utilities are in the folder scss/util, and broken up into multiple files by category. You can import every utility file at once using this line of code:

@import 'util/util';

Or, utilities can be imported individually.

// Color manipulation
@import 'util/color';

// Selector generation
@import 'util/selector';

// Unit manipulation and conversion
@import 'util/unit';

// Value checking and extraction
@import 'util/value';

Variables, functions, or mixins prefixed with -zf- are considered part of the internal API, which means they could change, break, or disappear without warning. We recommend sticking to only the public API, which is documented below.


Sass Reference

Variables

The default styles of this component can be customized using these Sass variables in your project's settings file.

NameTypeDefault ValueDescription
$primary-color null

Patch to fix issue #12080


Mixins

We use these mixins to build the final CSS output of this component. You can use the mixins yourself to build your own class structure out of our components.

add-foundation-colors

@include add-foundation-colors;

Transfers the colors in the $foundation-palette map into variables, such as $primary-color and $secondary-color. Call this mixin below the Global section of your settings file to properly migrate your codebase.


flex

@include flex;

Enables flexbox by adding display: flex to the element.


flex-align

@include flex-align($x, $y);

Horizontally or vertically aligns the items within a flex container.

ParameterTypeDefault ValueDescription
$x Keyword null

Horizontal alignment to use. Can be left, right, center, justify, or spaced. Or, set it to null (the default) to not set horizontal alignment.

$y Keyword null

Vertical alignment to use. Can be top, bottom, middle, or stretch. Or, set it to null (the default) to not set vertical alignment.


flex-align-self

@include flex-align-self($y);

Vertically align a single column within a flex row. Apply this mixin to a flex column.

ParameterTypeDefault ValueDescription
$y Keyword null

Vertical alignment to use. Can be top, bottom, middle, or stretch. Or, set it to null (the default) to not set vertical alignment.


flex-order

@include flex-order($order);

Changes the source order of a flex child. Children with lower numbers appear first in the layout.

ParameterTypeDefault ValueDescription
$order Number 0

Order number to apply.


flex-direction

@include flex-direction($direction);

Change flex-direction

ParameterTypeDefault ValueDescription
$direction Keyword row

Flex direction to use. Can be

  • row (default): same as text direction
  • row-reverse: opposite to text direction
  • column: same as row but top to bottom
  • column-reverse: same as row-reverse top to bottom

Functions

color-luminance

color-luminance($color)

Checks the luminance of $color.

ParameterTypeDefault ValueDescription
$color Color None

Color to check the luminance of.


color-contrast

color-contrast($color1, $color2)

Checks the contrast ratio of two colors.

ParameterTypeDefault ValueDescription
$color1 Color None

First color to compare.

$color2 Color None

Second color to compare.


color-pick-contrast

color-pick-contrast($base, $colors, $tolerance)

Checks the luminance of $base, and returns the color from $colors (list of colors) that has the most contrast.

ParameterTypeDefault ValueDescription
$base Color None

Color to check luminance.

$colors List $white
$black

Colors to compare.

$tolerance Number $global-color-pick-contrast-tolerance

Contrast tolerance.


smart-scale

smart-scale($color, $scale, $threshold)

Scales a color to be darker if it's light, or lighter if it's dark. Use this function to tint a color appropriate to its lightness.

ParameterTypeDefault ValueDescription
$color Color None

Color to scale.

$scale Percentage 5%

Amount to scale up or down.

$threshold Percentage 40%

Threshold of lightness to check against.


get-color

get-color($color)

Get color from foundation-palette

ParameterTypeDefault ValueDescription
$color key None

key from foundation-palette


direction-opposite

direction-opposite($dir)

Returns the opposite direction of $dir

ParameterTypeDefault ValueDescription
$dir Keyword None

Used direction between "top", "right", "bottom" and "left".


gcd

gcd($a, $b)

Finds the greatest common divisor of two integers.

ParameterTypeDefault ValueDescription
$a Number None

First number to compare.

$b Number None

Second number to compare.


pow

pow($base, $exponent)

Handles decimal exponents by trying to convert them into a fraction and then use a nth-root-algorithm for parts of the calculation

ParameterTypeDefault ValueDescription
$base Number None

The base number.

$exponent Number None

The exponent.


ratio-to-percentage

ratio-to-percentage($ratio)

Calculates the height as a percentage of the width for a given ratio.

ParameterTypeDefault ValueDescription
$ratio List None

Ratio to use to calculate the height, formatted as x by y.


zf-parse-fraction

zf-parse-fraction($fraction)

Parse the given $fraction to numerators and denumerators.

ParameterTypeDefault ValueDescription
$fraction * None

Value representing a fraction to parse. It can be formatted as 50%, 1 of 2, 1/2 or 50 (no denominator would be returned).


zf-is-fraction

zf-is-fraction($value, $allow-no-denominator)

Returns whether the given $value represents a fraction. Supports formats like 50%, 1 of 2, 1 per 2 or 1/2.

ParameterTypeDefault ValueDescription
$value * None

Value to test.

$allow-no-denominator Boolean false

If true, simple numbers without denominators like 50 are supported.


fraction-to-percentage

fraction-to-percentage($fraction, $denominator)

Calculate a percentage from a given fraction.

ParameterTypeDefault ValueDescription
$fraction Number or List None

Value representing a fraction to use to calculate the percentage, formatted as 50 (relative to $denominator), 50%, 1 of 2 or 1/2.

$denominator Number or List None

Default value to use as denominator when $fraction represents an absolute value.


divide

divide($divident, $divisor, $precision)

Divide the given $divident by the given $divisor.

ParameterTypeDefault ValueDescription
$divident Number None

The divident.

$divisor Number None

The divisor.

$precision Number None

The precision decimals for the division.


text-inputs

text-inputs($types, $modifier)

Generates a selector with every text input type. You can also filter the list to only output a subset of those selectors.

ParameterTypeDefault ValueDescription
$types List or Keyword

A list of text input types to use. Leave blank to use all of them.

$modifier Keyword ''

A modifier to be applied to each text input type (e.g. a class or a pseudo-class). Leave blank to ignore.


font-stack

font-stack($stack, $map)

Return a font stack list from a map. Equivalent to map-safe-get($name, $-zf-font-stack).

ParameterTypeDefault ValueDescription
$stack String None

Name of the font stack.

$map Map $-zf-font-stack

Map of font stacks to retrieve a list from.


strip-unit

strip-unit($num)

Removes the unit (e.g. px, em, rem) from a value, returning the number only.

ParameterTypeDefault ValueDescription
$num Number None

Number to strip unit from.


rem-calc

rem-calc($values, $base)

Converts one or more pixel values into matching rem values.

ParameterTypeDefault ValueDescription
$values Number or List None

One or more values to convert. Be sure to separate them with spaces and not commas. If you need to convert a comma-separated list, wrap the list in parentheses.

$base Number null

The base value to use when calculating the rem. If you're using Foundation out of the box, this is 16px. If this parameter is null, the function will reference the $global-font-size variable as the base.


unitless-calc

unitless-calc($value, $base)

Converts a pixel, percentage, rem or em value to a unitless value based on a given font size. Ideal for working out unitless line heights.

ParameterTypeDefault ValueDescription
$value Number None

Value to convert to a unitless line height

$base Number None

The font size to use to work out the line height - defaults to $global-font-size


has-value

has-value($val)

Determine if a value is not falsey, in CSS terms. Falsey values are null, none, 0 with any unit, or an empty list.

ParameterTypeDefault ValueDescription
$val Mixed None

Value to check.


get-side

get-side($val, $side)

Determine a top/right/bottom/right value on a padding, margin, etc. property, no matter how many values were passed in. Use this function if you need to know the specific side of a value, but don't know if the value is using a shorthand format.

ParameterTypeDefault ValueDescription
$val List or Number None

Value to analyze. Should be a shorthand sizing property, e.g. "1em 2em 1em"

$side Keyword None

Side to return. Should be top, right, bottom, or left.


get-border-value

get-border-value($val, $elem)

Given border $val, find a specific element of the border, which is $elem. The possible values for $elem are width, style, and color.

ParameterTypeDefault ValueDescription
$val List None

Border value to find a value in.

$elem Keyword None

Border component to extract.


map-deep-get

map-deep-get($map, $keys...)

Finds a value in a nested map.

Learn more: Deep Get/Set in Maps

ParameterTypeDefault ValueDescription
$map Map None

Map to pull a value from.

$keys... String None

Keys to use when looking for a value.


map-to-list

map-to-list($map)

Casts a map into a list.

Learn more:

ParameterTypeDefault ValueDescription
$map Map None

Map to pull a value from.


zf-str-join

zf-str-join($str1, $str1, $delimiter)

Return a join of the two given strings $str1 and $str2. If the two strings are not empty, they are separated by $delimiter.

ParameterTypeDefault ValueDescription
$str1 String null

First string to join.

$str1 String null

Second string to join.

$delimiter String null

Delimieter between $str1 and $str2.


map-safe-get

map-safe-get($map, $key)

Safely return a value from a map.

ParameterTypeDefault ValueDescription
$map Map None

Map to retrieve a value from.

$key String None

Name of the map key.