CSS margin-block: Logical Top and Bottom Margins

The CSS margin-block shorthand is a logical property that sets the margins on an element's block dimension, which typically corresponds to the top and bottom margins in standard horizontal layouts. Instead of tying layout strictly to physical screen orientations, margin-block adapts dynamically based on the document's writing mode, text direction, and script flow. This guide explains how the shorthand functions, its syntax, and how it logically maps to physical properties.

Understanding Logical Properties vs. Physical Properties

Traditional CSS properties like margin-top and margin-bottom are physical. They always apply space to the physical top and bottom of the screen, regardless of whether the content is written horizontally (like English) or vertically (like traditional Chinese or Japanese).

Logical properties, introduced to support modern internationalized layouts, operate relative to the flow of content:

  • Inline dimension: The direction along which text flows in a line (left-to-right or right-to-left in horizontal writing).
  • Block dimension: The direction in which new blocks or lines are stacked (top-to-bottom in horizontal writing, right-to-left or left-to-right in vertical writing).

The margin-block property controls the margins at the start and end of this block axis, abstracting away the physical orientation.

Syntax and Usage

The margin-block property is a shorthand for two individual logical properties:

  • margin-block-start
  • margin-block-end

It accepts standard CSS length values, percentages, or the auto keyword, and can take either one or two values.

One Value Syntax

When you specify a single value, it applies equally to both the start and end of the block dimension:

.card {
  margin-block: 2rem;
}

In a standard horizontal layout (writing-mode: horizontal-tb), this is equivalent to:

.card {
  margin-top: 2rem;
  margin-bottom: 2rem;
}

Two Value Syntax

When you specify two values, the first value applies to margin-block-start and the second value applies to margin-block-end:

.article-header {
  margin-block: 1rem 3rem;
}

In standard horizontal layout, this is equivalent to:

.article-header {
  margin-top: 1rem;
  margin-bottom: 3rem;
}

How Writing Modes Alter the Mapping

The true advantage of margin-block becomes visible when writing modes change:

  1. Horizontal Writing (writing-mode: horizontal-tb):
    • Blocks stack from top to bottom.
    • margin-block-start maps to physical margin-top.
    • margin-block-end maps to physical margin-bottom.
  2. Vertical Writing (writing-mode: vertical-rl):
    • Blocks stack from right to left.
    • margin-block-start maps to physical margin-right.
    • margin-block-end maps to physical margin-left.
  3. Vertical Writing (writing-mode: vertical-lr):
    • Blocks stack from left to right.
    • margin-block-start maps to physical margin-left.
    • margin-block-end maps to physical margin-right.

By utilizing margin-block, elements maintain consistent spatial relationships relative to the flow of text without needing separate CSS rules or media queries for localized layouts.

Why Use margin-block?

  • Concise Code: It eliminates the need to declare both margin-top and margin-bottom individually or use the physical four-value margin: 20px 0; shorthand, which risks unintentionally overwriting inline margins.
  • Internationalization (i18n): Sites intended for global audiences seamlessly switch between horizontal and vertical orientations without layout breakage.
  • Modern Best Practice: It aligns with the modern CSS component-driven design philosophy by keeping layout logic tied to content flow rather than viewport orientation.