New

Uniform CSS has now been officially released!
Read more


Utility Settings

Control individual properties settings.


Utility Settings

The utility setting allows you to configure how each properties are generated. For example, you can replace and extend variants for any given property.


How it works

Properties in Uniform CSS are constructed using a template data structure. By passing in your settings to the utility map, you can override the default data set for esch property. Each property has a set number of settings available and if a certain setting is not specified in your configuration, Uniform will fall back to the default setting value instead.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
text-align: (
shorthand: text,
responsive: false,
),
margin-top: (
shorthand: customMarginTop
)
)
)
);
/* main.css */
.text-left { text-align: left; }
.text-center { text-align: center; }
.text-right { text-align: right; }

.customMarginTop-1 { margin-top: 0.062rem; }
.customMarginTop-2 { margin-top: 0.125rem; }
...

Utility Settings Table

The following utility setting definitions apply.

Setting Type Description
shorthand string Shorthand word to represent property.
responsive boolean Set responsiveness.
responsive-pseudos boolean Responsiveness across pseudo variants.
properties list Raw CSS property.
custom-properties map Custom properties inclusion.
extra-selector string Extra selector attached to end
variants map Key value map of the variants.
pseudos list Supported pseudos.

Shorthand

The shorthand setting overrides the default keyword used to identify the property.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
margin-top: (
shorthand: customMarginTop
),
margin-right: (
shorthand: mr
)
)
)
);
/* main.css */
.customMarginTop-1 { margin-top: 0.062rem; }
.customMarginTop-2 { margin-top: 0.125rem; }
...

.mr-1
{ margin-right: 0.062rem; }
.mr-2 { margin-right: 0.125rem; }
...

Null Shorthand

If null is passed in as a value for shorthand the property will omit the shorthand and use the variant name to identify the property instead.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
display: (
shorthand: null,
variants: (
block: block,
flex: flex
)
)
)
)
);
/* main.css */
.block { display: block; }
.flex { display: flex; }
...

Responsive

The responsive setting enables or disables the responsiveness of a given property.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
text-align: (
responsive: true,
),
)
)
);
/* main.css */
@media (min-width: 768px) {
.sm\.text-left { text-align: left; }
.sm\.text-center { text-align: center; }
.sm\.text-right { text-align: right; }
}
@media (min-width: 1024px) {
.md\.text-left { text-align: left; }
.md\.text-center { text-align: center; }
.md\.text-right { text-align: right; }
}
@media (min-width: 1280px) {
.lg\.text-left { text-align: left; }
.lg\.text-center { text-align: center; }
.lg\.text-right { text-align: right; }
}

Responsive Pseudos

The responsive-pseudos setting when enabled, will enable responsiveness across pseudos. By default, responsive-pseudos is disabled for all Uniform CSS properties.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
float: (
responsive: true,
responsive-pseudos: true,
pseudos: (hover)
),
)
)
);
/* main.css */
@media (min-width: 768px) {
.sm\.float-left { float: left; }
.sm\.float-right { float: right; }

.sm\.hover\.float-left:hover { float: left; }
.sm\.hover\.float-right:hover { float: right; }
}
...

Extra Selectors

The extra-selector setting when defined, will apply CSS combinators to the end of the utility. This can be useful for achieving features such as the lobotomized owl.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
gutter-y: (
shorthand: gutter-y,
properties: (margin-top),
extra-selector: '> * + *',
variants: (
10: 10px;
);
),
)
)
);
/* main.css */
.gutter-y-10 > * + * {
margin-top: 10px;
}
...

Properties

The properties setting specifies the CSS property to include. You can include multiple properties to be applied.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
padding-x: (
shorthand: px,
properties: (
padding-left,
padding-right
)
),
)
)
);
/* main.css */
.px-0 {
padding-left: 0;
padding-right: 0;
}
.px-1 {
padding-left: 0.062rem;
padding-right: 0.062rem;
}
.px-2 {
padding-left: 0.125rem;
padding-right: 0.125rem;
}
...

Custom Properties

The custom-properties setting specifies custom properties to include with each property. This can be useful for properties that need to include resetting custom properties such as background-color. The custom-properties setting must be passed in as a map with key value pairs.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
background-color: (
custom-properties: (
--bg-ltn: 50%,
--bg-opacity: 1,
)
),
)
)
);
/* main.css */
.bg-red {
--bg-ltn: 50%,
--bg-opacity: 1,
background-color: ...;
}
.bg-blue {
--bg-ltn: 50%,
--bg-opacity: 1,
background-color: ...;
}
...

Variants

The variants setting specifies which variants should be generated for a given CSS property. Settings must be passed in as a map with key value pairs.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
margin: (
shorthand: m,
properties: (margin),
variants: (
1: 0.062rem,
2: 0.125rem,
custom: 180px,
)
),
)
)
);
/* main.css */
.m-1 {
margin: 0.062rem,
}
.m-2 {
margin: 0.125rem,
}
.m-custom {
margin: 180px,
}
...

Null Variants

If null is passed in as a value for a variant key the property will omit the variant and use the shorthand instead.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
transition-property: (
shorthand: transition,
properties: (transition-property),
variants: (
null: (
background-color,
border-color,
color,
fill,
stroke,
opacity,
box-shadow,
transform,
)
)
),
)
)
);
/* main.css */
.transition {
transition-property: background-color, border-color, color, fill, stroke, opacity, box-shadow, transform;
}
...

Pseudos

The pseudos setting specifies which pseudos set should be generated for a given CSS property. Settings must be passed in as a list.

// main.scss
@use "uniform" as * with (
$config: (
utility: (
background-color: (
pseudos: (
hover, focus, group-hover
)
),
)
)
);

Disabling Defaults

Passing in null will disable all default settings. If you wish to disable defaults and apply your own, you can do so by applying your own settings to the extend map.

// main.scss
@use "uniform" as * with (
$config: (
utility : (
background-color: (
variants: null,
pseudos: null,
extend: (
variants: (
mainRed: red,
mainBlue: blue
),
pseudos: (hover, focus)
)
)
)
)
);
/* main.css */
.bg-mainRed { background-color: red; }
.bg-mainBlue { background-color: blue; }