An object for injecting margin between elements to space them based on their contextual relationship, instead of being based on the element itself
<div class="stack">
<div>1/div>
<div>2</div>
<div>3</div>
</div>In this form, it looks and functions exactly like the
Tailwind space-y utility. But there are
several reasons why the Stack is an important layout object, and worthy of its own name and class.
We're used to styling elements directly, and 'attaching' those styles to a particular element. But the stack object
looks at the relationship between two elements, and styles based on that context.
A simple example may be styling blocks from a headless CMS. If a paragraph follows a paragraph, you may want a smaller spacing than if the next section heading were to follow the paragraph.
Some paragraph content
Some more paragraph content
Some paragraph content
<article class="stack">
<h3>An article section title</h2>
<p>Some paragraph content</p>
<p>Some more paragraph content</p>
<h3>A new section!</h2>
<p>Some paragraph content</p>
</article>In fact, this is exactly the same concept on which the prose utility from
the tailwindcss-typography plugin is based on. It styles
the relationship between elements, rather than the elements themselves, to give them their spacing.
You can add some of your own CSS to create these relationships. Here's a simple form example:
.stack--form {
> * + * {
--stack-space: theme('spacing.6');
}
> label + input,
> label + textarea {
--stack-space: theme('spacing.1');
}
}Right now, Captain doesn't implement any of these relationships for you by default, but it's something we're considering for the future.
See customization options for more information on customizing the spacing between the stack items.
You can also build stacking contexts on the fly, using nested stacks.
The above form example inline could look like:
<form class="stack stack--6">
<p>All fields are required</p>
<div>
<div class="stack stack--1">
<label for="name">Name:</label>
<input id="name" name="name">
</div>
</div>
<div>
<div class="stack stack--1">
<label for="message">Message:</label>
<textarea id="message" name="message"></textarea>
</div>
</div>
</form>When nesting stacks like this, it's important that each nested stack is wrapped in an extra element. Otherwise, it will change the spacing for itself as well, and will not receive the correct spacing.
Wrap nested stacks in an element
<div class="stack">
<div>
<div class="stack stack--6">
<p>...</p>
<p>...</p>
</div>
</div>
</div>Don't forget or the nested stack will not get the correct margin-top from its parent stack
<div class="stack">
- <div>
<div class="stack stack--6">
<p>...</p>
<p>...</p>
</div>
- </div>
</div>See customization options for more information on customizing the spacing between the stack items.
The Stack is an extremely useful layout tool, and can be used widely across a website.
That's why it's important to give it a name: it gives developer's the ability to talk about the concept and immediately understand, without having to explain it.
It's also useful when reading source code, to give you an immediate understanding of what a particular layout is.
When you see the class stack, you know what you're working with. This is particularly true for nested stacks, or where
other classes within and around the stack may be doing something similar. It allows the primitive layout objects to stand out.
The stack class also includes spacing modifiers out of the box.
The default config creates these claseses
from Tailwind's space config, which in turn defaults to
Tailwind's global spacing config.
A stack without a modifier defaults to a spacing of 1rem.
<div class="stack">
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
</div>
<div class="stack stack--8">
<div>An item</div>
<div>Another item</div>
<div>One more item</div>
</div>See customization options for more information on customizing the spacing between the stack items.
You can reverse the order of your stack using the stack--reverse modifier class. This will ensure the spacing is
applied to the correct side of the elements in the stack.
<div class="stack stack--reverse">
<div>1</div>
<div>2</div>
<div>3</div>
</div>The stack object can have its spacing and reverse-order set at different breakpoints:
<div class="stack md:stack--6 lg:stack--8 lg:stack--reverse">
<div>...</div>
<div>...</div>
</div>To change the gaps available to the stack class, specify the name and gap size using the gap option in the theme.stack section of your config file:
// tailwind.config.js
module.exports = {
theme: {
stack: (theme) => ({
+ gap: {
+ DEFAULT: '1rem',
+ ...theme('space'),
+ },
}),
},
}If you only have a single stack gap size, you can specify a single size as a shorthand:
// tailwind.config.js
module.exports = {
theme: {
stack: {
+ gap: '1rem',
},
},
}By default, only responsive variants are generated for stack utilities.
You can control which variants are generated for the stack utilities by modifying the stack 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: {
// ...
+ stack: [],
}
}If you don't plan to use the stack utilities in your project, you can disable them entirely by setting the stack property to false in the captain.plugins section of your config file:
// tailwind.config.js
module.exports = {
captain: {
plugins: {
// ...
+ stack: false,
}
}
}