Display

Control how an element generates boxes with block, inline, flex, grid, hidden and the rest — the first decision in every layout.

display decides what kind of box an element creates and how its children are laid out. Almost every layout problem starts here.

Overview#

<div class="space-y-3 p-4 text-sm">
  <div class="rounded bg-indigo-100 p-2 text-indigo-900">block — fills the width, starts a new line</div>
  <div>
    <span class="rounded bg-emerald-100 p-2 text-emerald-900">inline</span>
    <span class="rounded bg-emerald-100 p-2 text-emerald-900">flows with text</span>
  </div>
  <div class="flex gap-2 rounded bg-amber-50 p-2">
    <span class="rounded bg-amber-200 px-2 py-1 text-amber-900">flex</span>
    <span class="rounded bg-amber-200 px-2 py-1 text-amber-900">children in a row</span>
  </div>
  <div class="grid grid-cols-3 gap-2 rounded bg-sky-50 p-2">
    <span class="rounded bg-sky-200 px-2 py-1 text-center text-sky-900">grid</span>
    <span class="rounded bg-sky-200 px-2 py-1 text-center text-sky-900">in</span>
    <span class="rounded bg-sky-200 px-2 py-1 text-center text-sky-900">columns</span>
  </div>
</div>

Reference#

When to use which#

block vs inline-block vs inline#

• inline ignores width, height and vertical margin. Padding renders but does not push surrounding lines apart.
• inline-block respects all box properties while still sitting in the text flow — good for badges and buttons inside a paragraph.
• block takes the full available width and starts a new line.

<p class="max-w-md p-4 text-sm leading-loose text-gray-700">
  A status of
  <span class="inline-block rounded-full bg-emerald-100 px-2 py-0.5 text-xs font-semibold text-emerald-800">Active</span>
  sits neatly in the sentence because <code class="rounded bg-gray-100 px-1">inline-block</code> accepts vertical padding.
</p>

flex vs grid#

Rule of thumb: if you are describing a line of things, use Flexbox. If you are describing a matrix, use Grid. See Flexbox and Grid.

flow-root#

Creates a new block formatting context. Two things it fixes:

<!-- 1. Contains floated children -->
<div class="flow-root">
  <img class="float-left mr-4" src="…" alt="">
  <p>Text wraps, and the parent still has height.</p>
</div>

<!-- 2. Stops the first child's margin escaping the parent -->
<div class="flow-root bg-gray-100">
  <p class="mt-8">The margin stays inside the grey box.</p>
</div>

contents#

Removes the wrapper's own box so its children participate in the grandparent's layout. Useful when a component adds a wrapper that would otherwise break a grid.

<div class="grid grid-cols-3 gap-4">
  <div class="contents">
    <div>1</div>
    <div>2</div>
    <div>3</div>
  </div>
</div>

Hiding elements#

There are three different meanings of "hidden", and they are not interchangeable.

<div class="space-y-2 p-4 text-sm">
  <button class="inline-flex items-center gap-2 rounded-md bg-gray-900 px-3 py-2 text-white">
    <svg class="size-4" fill="none" stroke="currentColor" stroke-width="2" viewBox="0 0 24 24"><path stroke-linecap="round" d="M5 12h14m-7-7v14"/></svg>
    <span class="sr-only">Add item</span>
  </button>
  <p class="text-gray-600">The button above is icon-only but still announces "Add item".</p>
</div>

Use not-sr-only to reveal it again at a breakpoint: sr-only sm:not-sr-only.

Common patterns#

Responsive show/hide#

<nav class="hidden md:flex">Desktop navigation</nav>
<button class="md:hidden">Open menu</button>

Icon and label alignment#

<a href="#" class="inline-flex items-center gap-2 text-indigo-600 hover:text-indigo-500">
  <svg class="size-4" …></svg>
  Documentation
</a>

inline-flex keeps the link inline while aligning the icon to the text.

Toggling with data-*#

<div data-open="false" class="hidden data-[open=true]:block">…</div>

Common mistakes#

• Setting width on an inline element. It has no effect. Use inline-block.
• Using hidden for content that should stay available to screen readers. Use sr-only.
• Reaching for opacity-0 to hide interactive content. It stays focusable and announced. Pair with pointer-events-none and aria-hidden, or use hidden.
• flex on the item instead of the container. flex makes an element's children flex items.
• Expecting gap-* to work without flex or grid. It does nothing on a block element.

Related topics#

• Flexbox — one-dimensional layout
• Grid — two-dimensional layout
• Position — taking elements out of flow
• Overflow & Layering — clipping and stacking