Compass Core: Utilities Module

Check out the Utilities Demo to witness many of the Compass Utilities in action.

The Utilities Module provides a wealth of useful mixins to make common styling tasks easy. It also provides common tools to be shared by compass frameworks. The Utilities Module is broken up into a number of sub-modules. Each sub-module is then further broken up into its own sub-modules (sub-sub-modules?). You can import the entire Utilities Module with one import command:

@import compass/utilities.sass

or you can selectively import specific utility sub-modules:

@import compass/utilities/[submodule].sass

or you can selectively import specific utility sub-sub-modules:

@import compass/utilities/[submodule]/[subsubmodule].sass

The Utilities Module does not generate any CSS, it only provides mixins.

General Utilities

The General Utilities sub-module contains the following sub-modules:

Sub-Module	Mixin	Description
clearfix	+clearfix	Provides float clearing so that the bottom of an element containing floated elements falls below them. Uses the overflow:hidden strategy. A width is recommended. See also comments below.
	+pie-clearfix	float clearing using generated content: PIE Easy Clearing. See also comments below.
float	+float-left	float:left with fix for double-margin bug
	+float-right	float:right with fix for double-margin bug
	+float(side)	alternate syntax for the above two
hacks	+has-layout	makes IE6 get layout (restores display to “block”)
	+bang-hack(property, hack_value, value)	uses the !important hack to set a different property value for IE6 and below
reset	many mixins	see Reset Module documentation
tag_cloud	+tag-cloud([base_size])	Provides class names that adjust the font-sizes for a tag cloud.

More about clearfix:

The overflow:hidden technique (+clearfix) has its side-effects, but it covers many cases, and it’s short. There are two specific situations where this technique would cause you problems, where content needs to show outside the box:

• Suckerfish-style dropdowns
• box-shadow or other CSS3 transformations (see blog post)

The content:after technique (+pie-clearfix) avoids these side-effects, but it is verbose. Compass will cause a fair amount of repetition in the output, so this mixin is not the default. You can get around this by grouping clearfixed rules:

.check-one, .check-two
  +pie-clearfix

The bottom line is that Compass has to make a compromise. The +pie-clearfix mixin would probably be a stronger default to avoid side-effects, but the simpler overflow:hidden method is preferable to avoid massive repetition. As long as you’re aware of the issues +clearfix can present, you can decide where to switch methods or plan ahead by grouping your +pie-clearfix rules together.

You can import the entire General Utilities sub-module:

@import compass/utilities/general.sass

or you can selectively import specific sub-modules:

@import compass/utilities/general/[submodule].sass

The reset submodule is a bit special though — see below.

Reset Utilities

The Reset Utilities (a sub-module of the General Utilities sub-module) are a bit unique. Since reset facilities are used often, a core Reset Module was created that @imports all of the Reset Utilities. (I suppose was done to give this sub-sub-module more visibility). See the Reset Module page for mixin documentation.

You can import the Reset Module with:

@import compass/reset

However, note that compass/_reset.sass contains “+global-reset”. So, the above @import causes reset styles to be added to the generated CSS.

If you only want the mixins, import the normal way:

@import compass/utilities/general/reset.sass

Link Utilities

The Link Utilities sub-module provides utilities for dealing with anchor links. It is broken into several sub-modules. You can import them selectively or all at once with:

@import compass/utilities/links.sass

You can import any Link Sub-Module with:

@import compass/utilities/links/[submodule].sass

Sub-Module	Mixin	Description
hover_link	+hover-link	Styles a link that only has an underline when you hover over it.
link_colors	+link-colors(normal[, hover, active, visited, focus])	Set all the colors for a link with one mixin call. Order of arguments is: normal, hover, active, visited, focus. States not specified are left alone. Mixin like so: a +link-colors(#00c, #0cc, #c0c, #ccc, #cc0) Generated CSS order is LVFHA
unstyled_link	+unstyled-link	A link that looks and acts like the text it is contained within.

List Utilities

The List Utilities sub-module provides utilities for dealing with ordered and unordered lists. It is broken into several sub-modules. You can import them selectively or all at once with:

@import compass/utilities/lists.sass

You can import any List Sub-Module with:

@import compass/utilities/lists/[submodule].sass

Sub-Module	Mixin	Description
bullets	+no-bullet	Turn off the bullet for an element of a list.
	+no-bullets	Turn off all the bullets for a list.
	+pretty-bullets(bullet_icon, width, height[, line_height, padding])	Makes a list use a background image for a bullet. It should be used like this for an icon that is 5×7: ul.pretty +pretty-bullets(/images/my-icon.png, 5px, 7px)
horizontal_list	+horizontal-list([padding])	A list that is laid out such that the elements are floated left and won’t wrap. This is not an inline list.
inline_list	+inline-list	Makes a list inline so that it will flow like normal text.
	+comma-delimited-list	Like an inline list, but with elements separated by commas. This will not work in all browsers. More info.

Table Utilities

The Table Utilities sub-module provides utilities for dealing with tables. It is broken into several sub-modules. You can import them selectively or all at once with:

@import compass/utilities/tables.sass

You can import any Table Sub-Module with:

@import compass/utilities/tables/[submodule].sass

Sub-Module	Mixin	Description
alternating_rows_and_columns	+alternating-rows-and-columns(even_row_color, odd_row_color, dark_intersection)	Sets background colors for a table so that rows and columns alternate and are shaded correctly. This requires that you annotate your table rows with .even or .odd and your columns with .even or .odd
scaffolding	+table-scaffolding	Sets some basic styles for the table’s cells and defines a .numeric class for them.
borders	+outer-table-borders([width, color])	Sets the borders for the outside of the table and the headers and footer.
borders	+inner-table-borders([width, color])	Sets the borders for the inside of the table.

Text Utilities

The Text Utilities sub-module provides utilities for dealing with text. It is broken into several sub-modules. You can import them selectively or all at once with:

@import compass/utilities/text.sass

You can import any Text Sub-Module with:

@import compass/utilities/text/[submodule].sass

Sub-Module	Mixin	Description
nowrap	+nowrap	Remembering whether or not there’s a hyphen in white-space is too hard.
replacement	+replace-text(img[, x, y])	Hides html text and replaces it with an image. If you use this on an inline element, you will need to also set the display to either block or inline-block.