Foundation
Jump to Nav

# 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

### 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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$order` | Number | `0` | Order number to apply.

#### flex-direction

    @include flex-direction($direction);

Change flex-direction

Parameter | Type | Default Value | Description
--- | --- | --- | ---

`$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`.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$color` | Color | `None` | Color to check the luminance of.

#### color-contrast

    color-contrast($color1, $color2)

Checks the contrast ratio of two colors.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$color1` | Color | `None` | First color to compare.
`$color2` | Color | `None` | Second color to compare.

#### color-pick-contrast

    color-pick-contrast($color1, $color2)

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

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$color1` | Color | `None` | First color to compare.
`$color2` | Color | `None` | Second color to compare.

#### 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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$color` | key | `None` | key from foundation-palette

#### direction-opposite

    direction-opposite($dir)

Returns the opposite direction of $dir

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$dir` | Keyword | `None` | Used direction between "top", "right", "bottom" and "left".

#### gcd

    gcd($a, $b)

Finds the greatest common divisor of two integers.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$ratio` | List | `None` | Ratio to use to calculate the height, formatted as `x by y`.

#### 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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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)`.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$num` | Number | `None` | Number to strip unit from.

#### rem-calc

    rem-calc($values, $base)

Converts one or more pixel values into matching rem values.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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 `$base-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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$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:

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$map` | Map | `None` | Map to pull a value from.

#### map-safe-get

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

Safely return a value from a map.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$map` | Map | `None` | Map to retrieve a value from.
`$key` | String | `None` | Name of the map key.