Bourbon – Sass Mixin Library

A simple and lightweight mixin library for Sass.

Bourbon is a comprehensive library of sass mixins that are designed to be simple and easy to use. No configuration required.
The mixins aim to be as vanilla as possible, meaning they should be as close to the original CSS syntax as possible.

The mixins contain vendor specific prefixes for all CSS3 properties for support amongst modern browsers. The prefixes also ensure graceful degradation for older browsers that support only CSS3 prefixed properties. Bourbon uses SCSS syntax.

Install BourbonView on Github

Mixins

Animations View source

The animation mixins support comma separated lists of values, which allows different transitions for individual properties to be described in a single style rule. Each value in the list corresponds to the value at that same position in the other properties.

box:hover {
  @include animation-name(scale, slide);
  @include animation-duration(2s);
  @include animation-timing-function(ease);
  @include animation-iteration-count(infinite);

  // Animation shorthand works the same as the CSS3 animation shorthand
  @include animation(scale 1.0s ease-in, slide 2.0s ease);
}

Demo

Appearance View source

The appearance CSS property is used to display an element using a platform-native styling based on the operating system's theme.

@include appearance(none);

Background Image View source

The background-image mixin is helpful for chaining multiple comma delimited background images and/or linear/radial-gradients into one background-image property. The Background-image mixin supports up to 10 background-images.

Use in combination with the linear-gradient function and the radial-gradient function.

// Multiple image assets
@include background-image(url("/images/a.png"), url("images/b.png"));

// Image asset with a linear-gradient
@include background-image(url("/images/a.png"), linear-gradient(white 0, yellow 50%, transparent 50%));

// Multiple linear-gradients - Demo
@include background-image(linear-gradient(hsla(0, 100%, 100%, 0.25) 0%, hsla(0, 100%, 100%, 0.08) 50%, transparent 50%), 
                           linear-gradient(#4e7ba3, darken(#4e7ba4, 10%)));

// NOT SUPPORTED - Multiple image assets with shorthand notation
@include background-image(url("/images/a.png") center no-repeat, url("images/b.png") left repeat);

Demo

Note about shorthand notation

All CSS background properties support comma delimited values. For multiple background images you can specify the background properties like position, repeat, etc. for each image. For example:

@include background-image(url("/images/a.png"), url("images/b.png"));
background-position: center top, center;
background-repeat: no-repeat, repeat-x;

Background SizeView source

The background-size mixin supports multiple background-sizes for use with multiple background-images via comma delimitation.

@include background-size(50% 100%); // Single
@include background-size(50% 100%, 75% 100%); // Multiple

Border ImageView source

Border-image supports short-hand notation.

@include border-image(url(/images/border.png) 27 repeat);

Demo

Border Radius View source

The border-radius mixin can take short-hand notation or the full radius expression.

@include border-radius(10px);
@include border-radius(5px 5px 2px 2px);

You can also specify individual corners.

@include border-top-left-radius(5px);
@include border-top-right-radius(5px);
@include border-bottom-right-radius(5px);
@include border-bottom-left-radius(5px);

Individual sides are supported as well.

@include border-top-radius(5px);
@include border-bottom-radius(5px);
@include border-left-radius(5px);
@include border-right-radius(5px);

Box ShadowView source

Box-shadow supports single or multiple arguments.

Single Box Shadow

@include box-shadow(0 0 5px 3px hsla(0, 0%, 0%, 0.65));

Multiple Box Shadows

@include box-shadow(1px 1px 5px 1px green, -1px -1px 5px 1px blue);

Box SizingView source

Box-sizing will change the box-model of the element it is applied to.

@include box-sizing(border-box);

Columns View source

All current CSS3 column properties are supported. See the complete list of mixins for more info.

@include columns(12 8em);
@include column-rule(1px solid green);

Flex Box View source

The flex-box mixin is based on the 2009 w3c spec. More info

div.parent {
  @include display-box;
  @include box-align(start);
  @include box-orient(horizontal);
  @include box-pack(start);
}

div.parent > div.child {
  @include box-flex(2);
}

// Alternative custom shorthand mixin.
div.parent {
  @include box($orient: horizontal, $pack: center, $align: stretch); // defaults
  @include box(vertical, start, stretch);
}

Inline Block View source

The inline-block mixin provides support for the inline-block property in IE6 and IE7.

@include inline-block;

Linear Gradient View source

Gradient Position is optional, default is top. Position can be a degree (90deg). Mixin supports up to 10 color-stops.

This mixin will output a fallback background-color: #first-color; declaration. A $fallback argument can be passed to change the fallback color.

@include linear-gradient(#1e5799, #2989d8);
@include linear-gradient(top, #8fdce5, #3dc3d1);
@include linear-gradient(top, #8fdce5, #3dc3d1, $fallback: red);
@include linear-gradient(50deg, #1e5799 0%, #2989d8 50%, #207cca 51%, #7db9e8 100%);

Optional variables can be passed to control the deprecated -webkit-gradient() function (iOS 4):
$deprecated-pos1, $deprecated-pos2

@include linear-gradient(#1e5799, #3dc3d1, $deprecated-pos1: left center, $deprecated-pos2: left top);

Demo

Radial Gradient View source

Takes up to 10 gradients. See also the background-image mixin.

This mixin will output a fallback background-color: #first-color; declaration. A $fallback argument can be passed to change the fallback color.

@include radial-gradient(#1e5799, #3dc3d1);
@include radial-gradient(50% 50%, circle cover, #eee 10%, #1e5799 30%, #efefef);
@include radial-gradient(50% 50%, circle cover, #eee 10%, #1e5799 30%, #efefef, $fallback: red);

Optional variables can be passed to control the deprecated -webkit-gradient() function (iOS 4):
$deprecated-pos1, $deprecated-pos2, $deprecated-radius1, $deprecated-radius2

@include radial-gradient(#1e5799, #3dc3d1,
                         $deprecated-pos1: left center, $deprecated-pos2: left top,
                         $deprecated-radius1: 50, $deprecated-radius2: 360);

Demo

Transform & Transform-origin View source

@include transform(translateY(50px));

@include transform-origin(center top);

Transitions View source

Shorthand mixin: Supports multiple parentheses-delimited values for each variable.

@include transition (all 2.0s ease-in-out);
@include transition (opacity 1.0s ease-in 0s, width 2.0s ease-in 2s);

User-select View source

Controls the appearance (only) of selection. This does not have any affect on actual selection operation.

@include user-select(none);

Functions

Compact View Source

The compact function will strip out any value from a list that is false. Takes up to 10 arguments.

$full:  compact($name-1, $name-2, $name-3, $name-4, $name-5, $name-6, $name-7, $name-8, $name-9, $name-10);

Flex Grid View source

Use this mixin to easily create a flexible-grid layout.

The $fg-column, $fg-gutter and $fg-max-columns variables must be defined in your base stylesheet to properly use the flex-grid function.

This function takes the fluid grid equation (target / context = result) and uses columns to help define each.

$fg-column: 60px;             // Column Width
$fg-gutter: 25px;             // Gutter Width
$fg-max-columns: 12;          // Total Columns For Main Container

div {
  width: flex-grid(4);        // returns (315px / 1020px) = 30.882353%;
  margin-left: flex-gutter(); // returns (25px / 1020px) = 2.45098%;

  p {
    width: flex-grid(2, 4);   // returns (145px / 315px) = 46.031746%;
    float: left;
    margin: flex-gutter(4);   // returns (25px / 315px) = 7.936508%;
  }

  blockquote {
    float: left;
    width: flex-grid(2, 4);   // returns (145px / 315px) = 46.031746%;
  }
}

Golden Ratio View Source

Returns the golden ratio of a given number. Must provide a pixel or em value for the first argument. Also takes a required integer for an increment value: ...-3, -2, -1, 0, 1, 2, 3...

Note: The golden-ratio function can be wrapped in sass's abs(), floor(), or ceil() functions to get the absolute value, round down, or round up respectively.

// Positive number will increment up the golden-ratio
font-size: golden-ratio(14px,  1);
// returns: 22.652px

// Negative number will increment down the golden-ratio
font-size: golden-ratio(14px, -1);
// returns: 8.653px

Resources: modularscale.com & goldenrationcalculator.com

Grid Width View source

Easily setup and follow a grid based design. Check out gridulator.com

The $gw-column and $gw-gutter variables must be defined in your base stylesheet to properly use the grid-width function.

$gw-column: 100px;          // Column Width
$gw-gutter: 40px;           // Gutter Width

div {
  width: grid-width(4);     // returns 520px;
  margin-left: $gw-gutter;  // returns 40px;
}

Linear Gradient View source

Outputs a linear-gradient. Use in conjunction with the background-image mixin. The function takes the same arguments as the linear-gradient mixin.

@include background-image(linear-gradient(white 0, yellow 50%, transparent 50%));

Optional variables can be passed to control the deprecated -webkit-gradient() function (iOS 4):
$deprecated-pos1, $deprecated-pos2

@include linear-gradient(#1e5799, #3dc3d1, $deprecated-pos1: left center, $deprecated-pos2: left top);

Demo

Modular Scale View Source

Returns the modular scale of a given number. Must provide a number value for the first argument. The second argument is a required integer for an increment value: ...-3, -2, -1, 0, 1, 2, 3... The third value is the ratio number.

Note: The function can be wrapped in sass's abs(), floor(), or ceil() functions to get the absolute value, round down, or round up respectively.

div {
 // Increment Up GR with positive value
 font-size:        modular-scale(14px,   1, 1.618); // returns: 22.652px

 // Increment Down GR with negative value
 font-size:        modular-scale(14px,  -1, 1.618); // returns: 8.653px

 // Can be used with ceil(round up) or floor(round down)
 font-size: floor( modular-scale(14px, 1, 1.618) ); // returns: 22px
 font-size:  ceil( modular-scale(14px, 1, 1.618) ); // returns: 23px
}

Resources: modularscale.com & goldenrationcalculator.com

Radial Gradient View source

Outputs a radial-gradient. Use in conjunction with the background-image mixin. The function takes the same arguments as the radial-gradient mixin.

@include backgorund-image( radial-gradient(#1e5799, #3dc3d1) );
@include background-image( radial-gradient(50% 50%, circle cover, #1e5799, #3dc3d1) );
@include background-image( radial-gradient(50% 50%, circle cover, #eee 10%, #1e5799 30%, #efefef) );

Optional variables can be passed to control the deprecated -webkit-gradient() function (iOS 4):
$deprecated-pos1, $deprecated-pos2, $deprecated-radius1, $deprecated-radius2

@include radial-gradient(#1e5799, #3dc3d1,
                         $deprecated-pos1: left center, $deprecated-pos2: left top,
                         $deprecated-radius1: 50, $deprecated-radius2: 360);

Demo

Tint & Shade View source

Tint and Shade are different from lighten() and darken() functions that are built into sass.

Tint is a mix of color with white.
Shade is a mix of color with black.
Both take a color and a percent argument.

background: tint(red, 40%);
background: shade(blue, 60%);

Add-ons

Buttons View source

The button add-on provides well-designed buttons with a single line in your CSS.

The mixin supports a style parameter and an optional color argument. The available button styles are:

  • simple (default)
  • shiny
  • pill

Simple Button Style

The mixin can be called with no arguments, which will render a blue button with the simple style.

button {
  @include button;
}

Pill Button Style

button {
  @include button(pill);
}

Shiny Button Style

Create beautiful buttons by defining a style and color argument; using a single color, the mixin calculates the gradient, borders, box shadow, text shadow and text color of the button. The mixin will change the text to be light when on a dark background, and dark when on a light background.

button {
  @include button(shiny, #ff0000);
}

Clearfix View source

This mixin will output a clearfix to the selector where the mixin is declared.

This clearfix uses Nicolas Gallagher's Micro Clearfix.

div {
  @include clearfix;
}

Font-Family View source

Bourbon defines four default font-families as variables for the sake of convenience:

font-family: $helvetica;
font-family: $georgia;
font-family: $lucida-grande;
font-family: $monospace;
font-family: $verdana;

CSS Output

font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
font-family: Georgia, Cambria, "Times New Roman", Times, serif;
font-family: "Lucida Grande", Tahoma, Verdana, Arial, sans-serif;
font-family: "Bitstream Vera Sans Mono", Consolas, Courier, monospace;
font-family: Verdana, Geneva, sans-serif;

Hide TextView Source

Hide-text is an image replacement mixin. It is based off the HTML5-Boilerplate image-replacement.

This image replacement technique is an alternative to the text-indent technique, which has performance and other benefits.

div {
  @include hide-text;
  background-image: url(logo.png);
}

HTML5 Input Types View source

This addon generates a variable which contains a list of all html5 input types that render as text-based inputs, excluding textarea. In other words, it allows for easy targeting of all inputs that mimic input[type="text"].

Note: You must use interpolation with the variable—#{}.

#{$all-text-inputs} {
  border: 1px solid green;
}

CSS Output

input[type="email"], input[type="number"],   input[type="password"], input[type="search"],
input[type="tel"],   input[type="text"],     input[type="url"],      input[type="color"],
input[type="date"],  input[type="datetime"], input[type="datetime-local"],
input[type="month"], input[type="time"],     input[type="week"] {
  border: 1px solid green;
}

Timing Functions View source

These CSS cubic-bezier timing functions are variables that can be used with CSS3 animations and transitions. The provided timing functions are the same as the jQuery UI demo: easing functions.

@include transition(all, 5s, $ease-in-circ);

Demo

Many of the timing functions below may look the same in this demo, but in complex animations, they are intricately different.

  • $ease-in-quad
  • $ease-out-quad
  • $ease-in-out-quad
  • $ease-in-cubic
  • $ease-out-cubic
  • $ease-in-out-cubic
  • $ease-in-quart
  • $ease-out-quart
  • $ease-in-out-quart
  • $ease-in-quint
  • $ease-out-quint
  • $ease-in-out-quint
  • $ease-in-sine
  • $ease-out-sine
  • $ease-in-out-sine
  • $ease-in-expo
  • $ease-out-expo
  • $ease-in-out-expo
  • $ease-in-circ
  • $ease-out-circ
  • $ease-in-out-circ
  • $ease-in-back
  • $ease-out-back
  • $ease-in-out-back

Complete List

All Supported Functions, Mixins, and Addons

@ denotes a mixin and must be prefaced with @include.

Mixins

animation
  @ animation(*args)
  @ animation-delay(*args)
  @ animation-direction(*args)
  @ animation-duration(*args)
  @ animation-fill-mode(*args)
  @ animation-iteration-count(*args)
  @ animation-name(*args)
  @ animation-play-state(*args)
  @ animation-timing-function(*args)

@ appearance(*args)
@ background-image(*args)
@ background-size(*args)
@ border-image(*args)

border-radius
  @ border-radius(*args)
  @ border-top-radius(*args)
  @ border-top-left-radius(*args)
  @ border-top-right-radius(*args)
  @ border-bottom-radius(*args)
  @ border-bottom-left-radius(*args)
  @ border-bottom-right-radius(*args)
  @ border-left-radius(*args)
  @ border-right-radius(*args)

@ box-shadow(*args)
@ box-sizing(*args)

columns
  @columns(*args)
  @column-count(*args)
  @column-fill(*args)
  @column-gap(*args)
  @column-rule(*args)
    @column-rule-color(*args)
    @column-rule-style(*args)
    @column-rule-width(*args)
  @column-span(*args)
  @column-width(*args)

flex-box
  @ box(*args)
  @ box-align(*args)
  @ box-direction(*args)
  @ box-flex(*args)
  @ box-flex-group(*args)
  @ box-lines(*args)
  @ box-ordinal-group(*args)
  @ box-orient(*args)
  @ box-pack(*args)
  @ display-box

@ inline-block
@ linear-gradient(*args)
@ radial-gradient(*args)

transform
  @ transform(*args)
  @ transform-origin(*args)

transition
  @ transition(*args)
  @ transition-delay(*args)
  @ transition-duration(*args)
  @ transition-property(*args)
  @ transition-timing-function(*args)

@ user-select

Functions

compact(*args)
flex-grid(*args)
golden-ratio(*args)
grid-width(*args)
linear-gradient(*args)
modular-scale(*args)
radial-gradient(*args)
shade(*args)
tint(*args)

Addons

@ button(*args)
@ clearfix
@ hide-text

HTML5 Inputs
  #{$all-text-inputs}

font-family
  $georgia
  $helvetica
  $lucida-grande
  $monospace
  $verdana

timing-functions
  $ease-in-*
  $ease-out-*
  $ease-in-out-*
  * = quad, cubic, quart, quint, sine, expo, circ, back