CSS border-top-width Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The border-top-width property controls the thickness of an element’s top border edge and is a core part of the visual box that surrounds content. It determines how much horizontal band of pixels (or device units) is painted along the top edge and contributes to the element’s outer dimensions when a visible border is present. Because a border only paints when it has a visible style, its effect depends on the element’s border style (for example, no width is visible if the border is suppressed by border-style being none or hidden).

Although it targets only the top side, border-top-width participates in the same cascade and specificity rules as other border properties and can be overridden by broader shorthands. For instance, setting values with the border-width shorthand (or with a full border shorthand) will replace per-side widths, so authors must be mindful of the order of declarations when combining side-specific and shorthand rules. It also follows inheritance and cascade semantics: it does not inherit by default, but can be influenced by higher-specificity rules or !important declarations.

In layout and rendering terms, the top border’s width affects hit-testing, painting order and how adjacent boxes flow - a thicker top border reduces available inner space and can change how backgrounds and shadows appear relative to content. Visually it can be used to create separators, emphasize element boundaries, or produce visual weight at the top of an element; because changing border thickness triggers repainting, heavy animation of border sizes can be more costly than animating transforms or opacity.

Finally, the property interoperates with other visual features: border clipping, border-radius, and any border images or complex backgrounds will use the top border’s width when calculating how the border area is drawn. When designing UI, consider both the aesthetic effect and layout consequences of increasing the top border’s width, since it affects both appearance and the element’s occupied space.

Definition

Initial value: medium
Applies to: All elements
Inherited: No
Computed value: Absolute length; '0' if the border style is 'none' or 'hidden'
Animatable: Yes
JavaScript syntax: object.style.borderTopWidth

Interactive Demo

The rusty swing set creaked a lonely lullaby in the twilight, shadows lengthening like grasping fingers across the dew-kissed grass. A lone dandelion seed, adrift on the breeze, whispered secrets of faraway fields, of dandelion suns and galaxies spun from fluff. Somewhere, beyond the veil of dusk, a coyote laughed, echoing through the stillness like a forgotten memory.

Syntax

border-top-width: <line-width>

Values

<line-width> = <length> | thin | medium | thick

thinLess than the default width.
mediumDefault value.
thickGreater than the default width.
<length>Floating-point number, followed by an absolute units designator (cm, mm, in, pt, or pc) or a relative units designator (em, ex, or px).
inherit

Example

HTML

<body>

  <h1>border-top-width examples</h1>

  <div class="example-grid">

    <div class="box thin">border-top-width: 1px</div>

    <div class="box medium">border-top-width: 5px</div>

    <div class="box thick">border-top-width: 12px</div>

    <div class="box thin-keyword">border-top-width: thin</div>

    <div class="box initial">border-top-width: initial</div>

  </div>

</body>

CSS

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  padding: 24px;
  background-color: #f5f7fa;
}

h1 {
  font-size: 20px;
  margin-bottom: 16px;
  color: #222;
}

.example-grid {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 480px;
}

.box {
  padding: 12px 16px;
  background-color: #fff;
  border: 1px solid rgba(0, 0, 0, 0.06);
  border-top-style: solid; /* ensure top border is visible */
  border-top-color: #1e88e5;
}

.box.thin {
  border-top-width: 1px;
}

.box.medium {
  border-top-width: 5px;
}

.box.thick {
  border-top-width: 12px;
}

.box.thin-keyword {
  border-top-width: thin;
}

.box.initial {
  border-top-width: initial;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS border-top-width property. Hover over a browser icon to see the version that first introduced support for this CSS property.