Functional utilities are utilities with a name and value.
Most of Tailwind’s utilities are functional utilities (like p-*). They are more advanced compared to the basic ones we have built in the last few chapters.
/* Basic utility */@utility name { /* Do something */}/* Functional utility */@utility name-* { /* Do something with '*' */}Here’s everything you need to know about functional utilities.
Two kinds of values
Functional utilities accept 2 kinds of values:
- Arbitrary values — those written in
[square_brackets] - Non-arbitrary values — those without square brackets.
<!-- arbitrary value --><div class="p-[20px]"></div><!-- non-arbitrary value --><div class="p-4"></div>Non-arbitrary values
Tailwind supports the 3 kinds of non-arbitrary values.
- Literal words like
initial - Bare values like
integer,number,percentage, orratio - Values that match a
@themedeclaration
Literal values
These are just words. They have to be defined in --value before Tailwind recognizes them as valid values.
The word auto is one example. For mx-auto to work, Tailwind has to define the auto keyword in their mx-* utility:
/* The utility */@utility mx-* { margin-inline: --value('auto'); /* other properties */}<!-- Usage --><div class="mx-auto"></div>/* Output */.mx-auto { margin-inline: 'auto';}If a property can take multiple different kinds of values, you can write them all in sequence. For example, a custom position-* utility that allows relative, absolute, static, and sticky values might look like this:
/* The utility */@utility position-* { position: --value('static', 'relative', 'absolute', 'sticky'); /* other properties */}<!-- Usage --><div class="position-absolute"></div>/* Output */.position-absolute { position: absolute;}Bare values
Tailwind accepts four types of values as “bare values”: integer, number, percentage and ratio. These are basically all just numbers in different formats.
So number is the one you want to use most of the time.
| Type | Example |
|---|---|
integer |
utility-50 |
number |
utility-50 utility-25.5 |
percentage |
utility-50% |
ratio |
utility-1/2 |
I don’t recommend supporting multiple types of bare values because it’s easy for a user to be confused about them, since they all kind of do the same thing.
For example, Tailwind uses the number type to create its opacity-* utility.
@utility opacity-* { opacity: --value(number)%;}Theme values
Theme values let you use the values you’ve determined in your Tailwind @theme declaration.
@theme { --spacing-section: ...; --color-blue-500: ...;}To use these values, you write the utility in such a way where * will replace the value you want to find. For example, if you want to use color from @theme, you write it like this:
@utility color-* { color: --value(--color-*);}Now, if you use color-blue-500, Tailwind replaces * with blue-500 and it looks for --color-blue-500.
<!-- Usage --><div class="color-blue-500">...</div>/* Output */.color-blue-500 { color: var(--color-blue-500);}Arbitrary values
Arbitrary values are those you put into [square_brackets]. Like bare values, Tailwind can detect the type of an arbitrary value as well.
- This includes bare value types like
integer,number,percentageandratio. - And other arbitrary-only types like:
absolute-size,angle,bg-size,color,family-name,generic-name,image,length,line-width,position,relative-size,url,vector, and*(which means any type).
You don’t need to know most of these types. In practice, the ones I use most are number, color, length, angle and *.
@utility name-* { width: --value([length]); /* supports a length type */ --prop: --value([*]); /* supports any value */}Tailwind will only create the CSS rule that uses that specific type. It will ignore other rules in the same utility if the type is not matched.
<!-- Utilities used --><div class="name-[50px] name-[200] name-red-500"></div>/* Output */.name-50px { width: 50px; }.name-200 { --prop: 200; }/* name-red-500 is not output because it was not used */Modifiers
Utilities that use modifiers have the name-value/modifier pattern.
<!-- The /50 is a modifier--><div class="bg-blue-500/50">...</div>At the time of writing, Tailwind uses modifiers only for two use cases.
| Use case | Example |
|---|---|
Add opacity to colours |
bg-blue-500/50 |
Add line-height to text |
text-md/1.3 |
To use a modifier, you need both --value and --modifier declarations.
- The
--valuewithout--modifieris used when no modifiers are present. - The
--valuewith--modifieris used when modifiers are present.
For example, when you support colours, you typically want to include both versions, like this:
@utility color-* { /* Non-modifier version */ color: --value(--color-*);
/* Works with modifiers */ color: oklch(from --value(--color-*) l c h / --modifier(integer) %);}When multiple values are present, Tailwind will detect and output both. But the last one wins according to CSS cascade rules.
Resolution order
If multiple types of values can be resolved the same way, you can put them within the same --value function. Values will be resolved left to right when placed this way.
A good example here is --color-* and [color]. For both, we just want Tailwind to output the color.
@utility color-* { /* Without modifiers */ color: --value(--color-*, [color]);
/* With modifiers */ color: oklch(from --value(--color-*, [color]) l c h / --modifier(number));}But if the output needs to be different — because you have to treat different types differently — then you have to create a new rule.
For example, a custom opacity-* utility can use both number and percentage — but they have to be written differently.
@utility custom-opacity-* { opacity: --value(number)%; opacity: --value(percentage);}Creating negative utilities
Some utilities like p and rotate can take in negative values.
<div class="-p-4 -rotate-5">...</div>If you want to create a utility that can support negative values, what you do is to create a new utility that begins with a - sign.
/* Example of a negative utility */@utility -p-* { padding: calc(var(--spacing) * --value(number) * -1);}Easier way to calculate spacing
One way to calculate spaces is to use the spacing variable you declared in the theme.
/* Declaring --spacing */@theme { --spacing: 0.25rlh;}
/* Using --spacing */@utility -p-* { padding: calc(var(--spacing) * --value(number) * -1);}This is generally a tedious way of doing so, because Tailwind has a --spacing function that lets you do the calculation. You can use it to save a few words.
/* These are equivalent */@utility p-* { padding: calc(var(--spacing) * --value(number)); padding: --spacing(--value(number));}This is all you need to know about functional utilities!
Welcome! Unfortunately, you don’t have access to this lesson. To get access, please purchase the course or enroll in Magical Dev School.
Unlock this lesson