Quasar Gutter Classes: q-gutter vs q-col-gutter

Every Quasar gutter question comes down to one choice: q-gutter-md or q-col-gutter-md. Put two col-6 children in a row with q-gutter-md and the second one drops to a new line. Swap in q-col-gutter-md and they sit side by side. The two class families look almost the same and do different things. This post shows what each one sets, why one breaks a 12-column row and the other doesn't, and the two rules that come with the one that works.

If you build your grid with the Flex & Grid Class Generator, it already picks the right one. The Quasar flex grid guide covers the row and col-* classes themselves. Here we only look at the space between them.

The two Quasar gutter class families

Both families put equal space between children, and both use a negative margin on the parent. They differ in what they set on the children:

The sizes don't refer to breakpoints. md in q-gutter-md means a medium gap, not "from 1024px". In Quasar 2.35.2 the gap sizes are:

Each family also has -x- and -y- versions for one direction only: q-gutter-x-md, q-col-gutter-y-lg. You can mix them on the same element, like q-col-gutter-x-xs q-col-gutter-y-lg.

The Quasar docs state the rule plainly: use q-gutter-* when the children have no col-* or offset-* class that sets a width, and q-col-gutter-* when they do. The rest of this post is the reason.

Why q-gutter breaks a 12-column row

Here is the broken version:

<div class="row q-gutter-md">
  <div class="col-6">Left</div>
  <div class="col-6">Right</div>
</div>

col-6 sets width: 50%. q-gutter-md then adds margin-left: 16px to each child. Margins sit outside the width, so the two children need 50% + 16px + 50% + 16px.

The parent's negative left margin of 16px makes the row 16px wider than its container, which pays for one of those margins. The other 16px has nowhere to go. The line is now wider than 100%, the row wraps, and "Right" drops below "Left".

The same thing happens with three col-4 children, four col-3 children, or any set of spans that adds up to exactly 12. Spans that add up to less than 12 survive, which is why the bug can hide for a while and then appear when someone changes col-5 to col-6.

How q-col-gutter keeps the 12-column math

Now the version that works:

<div class="row q-col-gutter-md">
  <div class="col-6">
    <div class="q-pa-md bg-grey-3">Left</div>
  </div>
  <div class="col-6">
    <div class="q-pa-md bg-grey-3">Right</div>
  </div>
</div>

Follow it step by step:

1. The parent gets margin-left: -16px. A block with an automatic width grows to fill its container, and a negative margin makes it reach 16px further. The row is now its container's width plus 16px, and starts 16px to the left of it.
2. Each child gets padding-left: 16px. Quasar sets box-sizing: border-box on every element, so padding is counted inside the width. col-6 is still exactly 50% of the row.
3. The first child's padding cancels the parent's negative margin. Its content starts where the container starts.
4. Every later child's padding becomes the gap. The 16px between "Left" and "Right" is the right child's padding.

So the widths still add up to 100%, the left edge lines up with the rest of the page, and there is a 16px gap between columns. That is the negative-margin trick. The top margin and padding do the same thing for rows that wrap onto several lines.

The two rules that come with q-col-gutter

The trick only works if nothing else touches those margins and paddings.

Style an inner element, not the col

The gap is padding inside each col-* element. Give that element a background or a border and it paints the gap too, so the columns look glued together. Put the visible element inside the col:

<!-- the background fills the gutter -->
<div class="col-6 bg-grey-3 q-pa-md">Left</div>

<!-- the background stops at the gutter -->
<div class="col-6">
  <div class="bg-grey-3 q-pa-md">Left</div>
</div>

The same goes for components. A q-card with class="col-6" directly inside a q-col-gutter-* row loses its gap. Wrap it in a div class="col-6".

Don't add padding classes like q-pa-md to the col either. They replace the gutter padding with their own.

Don't style the gutter parent

The parent sticks out by the gutter size on the top and left. A background or border on it shows up shifted, and a margin class like q-mt-md on it overrides the negative margin and breaks the alignment. Wrap the gutter row in another element and style that one:

<div class="bg-white rounded-borders q-pa-md">
  <div class="row q-col-gutter-md">
    <div class="col-12 col-md-4"><q-card flat bordered>...</q-card></div>
    <div class="col-12 col-md-8"><q-card flat bordered>...</q-card></div>
  </div>
</div>

The negative top margin also means the row's box reaches up into the element above it. If a button just above a gutter row stops responding to clicks near its bottom edge, that is the cause. The Quasar docs suggest putting the gutter row inside a wrapper that has the row or overflow-auto class.

When q-gutter is the right choice

q-gutter-* is for children that keep their own size: a group of buttons, chips, badges, or form fields with a fixed width. Margins don't change the children's inner size, so you can put backgrounds and borders straight on them.

<div class="q-gutter-sm">
  <q-btn color="primary" label="Save" />
  <q-btn outline color="primary" label="Preview" />
  <q-btn flat label="Cancel" />
</div>

It doesn't even need row: buttons are inline elements and the margins space them out as they wrap. For a toolbar or a chip list, this is the simpler choice.

A quick way to choose: if the children have a col-N or offset-N class, use q-col-gutter-*. If they don't, use q-gutter-*.

Quasar column spacing at different breakpoints

Core Quasar has no breakpoint versions of the gutter classes. If you need a smaller gap on phones, you have two options:

• The flex addon. With framework: { cssAddon: true } in the Quasar CLI config (or by importing quasar/src/css/flex-addon.sass), you get classes like q-col-gutter-sm q-col-gutter-md-lg: 8px gaps, and 24px from 1024px up. The docs warn that the addon adds noticeably to your CSS size.
• A Sass variable. The sizes come from $flex-gutter-xs to $flex-gutter-xl, which default to fractions of $space-base (16px). Override them in src/css/quasar.variables.sass to change every gutter in the app at once.

Common Quasar gutter questions

Why does my row have a horizontal scrollbar? Usually it doesn't come from the gutter, which only reaches left and up. Check for a col-* child that also has a margin class, or a q-gutter-* row with sized children.

Can I use a gutter on a column? Yes. The classes don't depend on direction, and q-col-gutter-y-* spaces col-* children that divide a column's height.

Does q-col-gutter work with offset-*? Yes. An offset is a left margin in percent on the child, and the gutter is padding inside it, so the two don't collide. That is why the docs group offset-* with col-* in the rule.

Next step

Set the gutter in the Flex & Grid Class Generator and look at the markup it writes: q-col-gutter-* on the row, and an inner div in every col for your content. Change the spans at each breakpoint, check the preview, and copy a grid where the gutter can't break the 12-column math.