CSS border playground

Educational guide to border

How to define borders and keep control of the box

A border defines the edge of a box. Learn to choose style, thickness and color, adapt sides to writing direction and preserve dimensions and focus.

Back to the playground

Mental model

border combines border-width, border-style and border-color on all four sides.

The layers of the box modelStatic diagram, not to scale: the border surrounds padding and content; margin sits outside.

1 · ContentThe text or elements inside the box.
2 · PaddingInner space between content and border.
3 · BorderThe edge you draw with thickness, style and color.
4 · MarginOuter space separating the box from other boxes.

The usual order is thickness, style and color: border: 2px solid uses currentColor, the element’s text color. Omitting thickness uses medium; omitting style uses none and the border is not drawn.

solid draws a continuous line; dashed and dotted use dashes or dots; double draws two lines within the total thickness. groove, ridge, inset and outset create relief effects. Choose a readable style and avoid communicating state through color alone.

Use border-width, border-style and border-color to change one dimension without resetting the others. Four values follow top, right, bottom, left order; two values address vertical and horizontal sides.

Physical and logical sides

Choose physical sides for a fixed position and logical sides to follow the content’s writing direction.

border-top, border-right, border-bottom and border-left target physical sides. border-block groups the start and end of the block axis; border-inline groups those of the text axis. border-inline-start follows direction and writing-mode: in horizontal writing it is left in LTR and right in RTL.

An accent that follows writing direction

LTR — Note with a leading accent

RTL — Note with a leading accent

The same CSS places the thick border at the start of the text: left in LTR and right in RTL. Thin dashed borders distinguish the remaining sides. This example does not demonstrate vertical writing.

An accent that follows writing direction

HTML

<p class="border-guide-accent" dir="ltr">LTR — Note with a leading accent</p>
<p class="border-guide-accent" dir="rtl">RTL — Note with a leading accent</p>

CSS

:root {
  color-scheme: light dark;
}

.border-guide-accent {
  box-sizing: border-box;
  margin: 0;
  padding: 1rem;
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
  background: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 94%, white), color-mix(in oklch, oklch(0.22 0.024 260) 92%, black));
  border-block-start: 2px dashed #38bdf8;
  border-inline-end: 2px dashed #38bdf8;
  border-block-end: 2px dashed #38bdf8;
  border-inline-start: 10px solid #f97316;
}

Border, outline and dimensions

border participates in the box model; outline is drawn without reserving space in layout.

With content-box, the declared width covers content: padding and border are added. With border-box, both fit inside the declared width and reduce content space. outline does not change that width and can overlap nearby elements.

Three boxes with the same declared width

With a 16 px root, 8rem equals 128 px. Without padding: content-box plus two 8 px borders measures 144 px; border-box measures 128 px; the outlined box measures 128 px in layout. Its outline extends outside.

Three boxes with the same declared width

HTML

<div class="border-guide-boxes">
  <button type="button" class="border-guide-box content-box">Border: content-box</button>
  <button type="button" class="border-guide-box border-box">Border: border-box</button>
  <button type="button" class="border-guide-box outline-box">Outline only</button>
</div>

CSS

:root {
  color-scheme: light dark;
}

.border-guide-boxes {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
  padding: 1rem;
}

.border-guide-box {
  inline-size: 8rem;
  padding: 0;
  border: 8px solid light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));
  color: light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
  background: light-dark(color-mix(in oklch, oklch(0.95 0.008 95) 94%, white), color-mix(in oklch, oklch(0.22 0.024 260) 92%, black));
  font: inherit;
  overflow-wrap: anywhere;

  &.content-box {
    box-sizing: content-box;
  }

  &.border-box {
    box-sizing: border-box;
  }

  &.outline-box {
    box-sizing: border-box;
    border: 0;
    outline: 8px solid light-dark(oklch(0.46 0.14 261), oklch(0.82 0.18 261));
  }

  &:focus-visible {
    outline: 3px dashed light-dark(oklch(0.22 0.01 95), oklch(0.95 0.01 95));
    outline-offset: 10px;
  }
}

The recipe adds a focus outline separated by outline-offset. Try it with Tab: it avoids size changes on focus and preserves a visible signal. Replace the project’s color tokens with your interface tokens when reusing the CSS.

Common mistakes

Before increasing thickness, check style, the cascade and the box model.

The border is invisible

Expected result: A visible line around the box.
Cause: border: 4px omits style; its initial value is none and the computed thickness becomes zero.
Solution: Specify a style, such as border: 4px solid, and check for a nonzero thickness.

The color or image disappears

Expected result: Change thickness while preserving everything else.
Cause: A later shorthand resets omitted values and border-image.
Solution: Use border-width to change thickness alone; declare border-image after the shorthand when needed.

The box grows or content narrows

Expected result: Preserve the intended size and readable content.
Cause: content-box adds padding and border; border-box subtracts them from content space.
Solution: Choose box-sizing deliberately, check minimum sizes and avoid increasing border thickness on focus if it shifts layout.

Focus is no longer visible

Expected result: Identify the active element using a keyboard.
Cause: outline is removed without another visible signal.
Solution: Keep native focus or provide a clear :focus-visible style; do not clip the outline with overflow.

Support and compatibility

Check the Baseline status of border and distinguish classic borders from other experimental properties.

border and logical borders are widely available features. The card reflects Baseline data; examples demonstrate native behavior in the current browser.

Explore outline and its distance from the border.