An object for clustering groups of dynamic width elements together, with a consistent space between them, even when stacking responsively
The cluster object is used when you want to evenly space several fluid-width elements, such as buttons or tags, both horizontally and vertically.
It applies an even margin on all sides of each element within the cluster, which makes them correctly spaced, even when wrapping onto multiple lines.
It then applies a negative margin around the whole element, which, with the help of overflow: hidden, chops off any excess margin that we don't want and pulls all the children flush against the container edge.
This makes the cluster perfectly space the items, without adding any extra margin on the outsides. Great!
Items are evenly spaced on all sides, even when wrapping
<div class="cluster">
<div>
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
<div>Another one</div>
<div>There are now 5 items in this cluster</div>
<div>Here is item six</div>
<div>Two more</div>
<div>Enough</div>
</div>
</div>The Cluster object in Captain provides a standardised way to define a cluster of items, and then use it effortlessly.
Note that the cluster has an extra element inside it that wraps the clustered items. This is to apply a negative margin that chops off the extra margin on the items inside, and pulls the cluster items flush against the container.
The following example shows the margin between the items, and the thick purple line is the container. Any margin outside the container is completely hidden and will not affect any other elements.
<div class="cluster">
<div> <!-- Extra div required unless using { support: { cssFlexGap } } -->
<div>1</div>
<div>2</div>
<div>3</div>
<div>4</div>
<div>5</div>
<div>6</div>
</div>
</div>Do include the extra element
<div class="cluster">
<div>
<div>An item</div>
</div>
</div>Don't forget the extra element, or your cluster items will be partially hidden
<div class="cluster">
- <div>
<div>An item that's cut off</div>
- </div>
</div>If you're using any kind of component-based framework or partials, you can easily move this extra div into a Cluster
component, which allows you to completely forget about it.
When support for Flex Gap (`gap`) becomes wider, we can drop this extra element. Support for it in Captain is already available. To make use of it early, add `flexGap` to the `captain.support` object in `tailwind.config.js`. At time of writing it's unavailable in Safari, and only recently in Chrome.
Clustered items are often lists, so it's useful to mark them up semantically. This helps screen readers know there is a list, and count how many items are in the list.
You could do the following:
<div class="cluster">
<ul>
<li>First list item</li>
<li>Second list item</li>
...
</ul>
</div>See customization options for more information on customizing the spacing between the cluster items.
The cluster class also includes spacing modifiers out of the box.
The default config creates these classes
from Tailwind's space config, which in turn defaults to
Tailwind's global spacing config.
A cluster without a modifier defaults to a spacing of 1rem.
<div class="cluster cluster--0.5">
<div>
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
<div>Another one</div>
<div>There are now 5 items in this cluster</div>
<div>Here is item six</div>
<div>Two more</div>
<div>Enough</div>
</div>
</div>
<div class="cluster cluster--8">
<div>
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
<div>Another one</div>
<div>There are now 5 items in this cluster</div>
<div>Here is item six</div>
<div>Two more</div>
<div>Enough</div>
</div>
</div>You can also size x and y spacing independently, using classes like cluster--x-8 and cluster--y-10.
<div class="cluster cluster--x-6 cluster--y-2">
<div>
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
<div>Another one</div>
<div>There are now 5 items in this cluster</div>
<div>Here is item six</div>
<div>Two more</div>
<div>Enough</div>
</div>
</div><div class="cluster cluster--1 md:cluster--2 lg:cluster--6 xl:cluster--8">
<div>
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
<div>Another one</div>
<div>There are now 5 items in this cluster</div>
<div>Here is item six</div>
<div>Two more</div>
<div>Enough</div>
</div>
</div>To change the gaps available to the cluster class, specify the name and gap size using the gap option in the theme.cluster section of your config file:
// tailwind.config.js
module.exports = {
theme: {
cluster: (theme) => ({
+ gap: {
+ DEFAULT: '1rem',
+ ...theme('space'),
+ },
}),
},
}If you only have a single cluster gap size, you can specify a single size as a shorthand:
// tailwind.config.js
module.exports = {
theme: {
cluster: {
+ gap: '1rem',
},
},
}By default, only responsive variants are generated for cluster utilities.
You can control which variants are generated for the cluster utilities by modifying the cluster property in the variants section of your tailwind.config.js file.
For example, this config will disable all variants:
// tailwind.config.js
module.exports = {
variants: {
// ...
+ cluster: [],
}
}If you don't plan to use the cluster utilities in your project, you can disable them entirely by setting the cluster property to false in the captain.plugins section of your config file:
// tailwind.config.js
module.exports = {
captain: {
plugins: {
// ...
+ cluster: false,
}
}
}