Repository navigation
Using a single value for grid :columns: prevents grid from re-arranging items #182
Description
Activity
Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! 🎉the grid does not re-arrange the items below each other for small screens but always keeps 2 items next to each other with the 8/4 size ratio (e.g.
1 1 2 2seems to be ignored).It's not that it's ignored, it's that you've overridden it. If the widths of the two items are fixed at 8/12 and 4/12, then then will always fit next to each other in the grid at any browser width.
The number-of-columns specification (
1 1 2 2) effectively sets the default width for each item in the grid — on small and medium screens, there's only one column so each item's default width will be 12. On large and x-large screens, having items arranged into 2 columns means that the default width of each item will be 6.So, it's not that the grid column count adjusts the size of the grid for different screen sizes. The grid is always 12 columns wide, no matter the browser width. It's the ITEM (default) sizes that get adjusted, based on the number of them that are supposed to fit on each row at any given size.
So, that's why setting explicit item widths overrides the default widths applied by the
.. grid::directive's column counts. If you're setting explicit item widths and you want the items to adjust size for different screen sizes, you have to specify the appropriate width for each breakpoint.Hey @ferdnyc
Thanks for the follow-up and the detailed explanation!I guess my expectation was that using a single value for
:columns:defines the effective "total width of the grid" irrespective of the number of items (and the actual item-widths are then adjusted to fit as good as possible within the assigned width).e.g. I expected the following 2 things to be the same:
(of course there are some ambiguities with sizes not divisible by the number of items).. grid:: 1 1 2 2 .. grid-item:: :columns: 8 8 4 4 A.. grid:: 1 1 2 2 .. grid-item:: :columns: 8 AAnyways, I fully understand your explanation and therefore I think we can close this issue.
*nod* It's worth trying out the examples in the (extensive) Bootstrap docs, in part because you can always pull them into stackblitz and play around with them interactively. For the most part, they apply equally to sphinx-design.
But with grid columns, the basic rule is that item widths have precedence. And widths are always set in percentages; the 12 "grid spaces" per row are just a convenient shorthand, to keep from having to do lots of division figuring out width percentages. In Bootstrap's CSS, the column count classes apply a percentage width rule to each child of the row, based on that count:
@mixin row-cols($count) { > * { flex: 0 0 auto; width: percentage(divide(1, $count)); } }
Which expands to,
.row-cols-2 > * { flex: 0 0 auto; width: 50%; } .row-cols-3 > * { flex: 0 0 auto; width: 33.3333%; }
...and so on. Applying a width class to the individual elements, though, does the same thing, and will override the
widthfrom the column-count rule:.col-3 { flex: 0 0 auto; width: 25%; }
The breakpoint-sized classes like
.col-sm-3and.row-cols-lg-4, just do the exact same thing, but inside@media (min-width: XXXpx)queries.In fact, on Bootstrap's page, another interesting example is one where they have a grid with four items in it, with the column count set to 4, and the width of one of the items (the third one) set to 6.
What that causes, at every screen width, is a layout where the first three items are on one row, and the last one wraps to occupy a second row at a quarter of the total width.
Forcing just that one item to occupy 6/12 grid columns (50% of the grid width) breaks the auto-layout, and means that the other three (each 25% wide) can no longer fit beside it at any breakpoint.
This is working as designed, though the docs don't make it clear enough — that part is being fixed (tracked in #265). A single grid argument (
.. grid:: 2) fixes the column count across all screen widths; the four-value form (.. grid:: 1 1 2 2) is what enables responsive re-flow, and per-item:columns:likewise accepts one or four values. For your example,.. grid:: 1 1 2 2with:columns: 12 12 8 8and12 12 4 4gives the stacking you expected on small screens. Closing as working-as-intended, with the docs clarification to follow.
Generated by Claude Code
Reacted by Frank Dana- added 2 commits that reference this issue
on Jul 12, 2026
Describe the bug
context
Not sure if this is considered a bug or not, but I thought I'll bring it up since it puzzled me for a moment...
If I use something like this:
Then the grid does not re-arrange the items below each other for small screens but always keeps 2 items next to each other with the 8/4 size ratio (e.g.
1 1 2 2seems to be ignored).If I specify explicit columns for each level, it does the job nicely:
expectation
I'd expect that the re-arrangement of items is still performed even if a single column-width is provided
... for the example above, I'd expect that on small-screens, the 2 items are shown below each other (however still with the size-ratio 8/4)
List your environment
sphinx-design 0.5.0