tailwindcss-concentric
v0.1.0
Published
Tailwind CSS v4 plugin: nested elements get the correct concentric corner radius automatically.
Maintainers
Readme
tailwindcss-concentric
Nested rounded corners that line up, for Tailwind CSS v4. Give a child rounded-concentric and its radius follows its rounded parent:

inner radius = outer radius - gap (gap = the distance between the two edges)The gap is the parent's padding and border width, plus the padding and border of a wrapper in between and the child's own margin. For absolute and fixed children it is the inset plus the parent's border width. The value is computed in CSS from the Tailwind classes you already wrote. No JavaScript, no config, and it keeps working when the parent's radius or padding changes, across breakpoints and states.
<div class="rounded-3xl bg-white p-3">
<img class="rounded-concentric" src="..." alt="" /> <!-- 24px - 12px = 12px -->
</div>Install
npm install tailwindcss-concentricImport it right after Tailwind in your main CSS file:
@import "tailwindcss";
@import "tailwindcss-concentric";Requires Tailwind CSS 4.0 or later. CI runs the browser suite against 4.0.0 and the latest release every week.
Classes
| Class | Effect |
|---|---|
| rounded-concentric | All four corners follow the nearest rounded ancestor. |
| rounded-{t,r,b,l}-concentric | Two corners on one side, e.g. rounded-t-concentric for media flush with the top of a card. |
| rounded-{s,e}-concentric | Start or end corners; they flip under dir="rtl". |
| rounded-{tl,tr,br,bl}-concentric | One physical corner. |
| rounded-{ss,se,ee,es}-concentric | One logical corner. |
| rounded-concentric-{n} / rounded-concentric-[6px] / rounded-concentric-(--gap) | Explicit gap instead of the measured one, for spacing the plugin cannot read (see What the plugin reads). {n} uses the spacing scale. |
| concentric-elliptical | Per-axis radii when the parent's padding differs per axis (see below). |
| concentric-squircle | corner-shape: squircle with a matching gap (see below). |
All of them work with variants (md:rounded-concentric, hover:rounded-t-concentric) and combine with plain radius classes on the same element, following the normal cascade: rounded-xl rounded-t-concentric gives concentric top corners and rounded-xl bottom corners.
Chains
Concentric elements pass their own radius and padding on, so nesting works at any of the levels you would realistically build (nine stacked rounded elements are exact):
<div class="rounded-3xl p-2"> <!-- 24px -->
<div class="rounded-concentric p-2"> <!-- 16px -->
<div class="rounded-concentric p-1"> <!-- 8px -->
<div class="rounded-concentric"></div> <!-- 4px -->
</div>
</div>
</div>A plain rounded-* element in the middle starts a new chain from its own radius.
Wrappers, margins and positioned elements
A wrapper without a radius passes its padding and border on, so layout divs between a card and its content need nothing. The child's own margin counts too, and a negative margin makes the radius larger, for media that bleeds to the card's edge:
<div class="rounded-3xl p-2"> <!-- 24px -->
<div class="flex flex-col gap-2 p-2"> <!-- plain wrapper -->
<div class="rounded-concentric"></div> <!-- 24 - 8 - 8 = 8px -->
</div>
</div>
<div class="rounded-3xl p-4">
<img class="-mx-4 -mt-4 rounded-t-concentric" /> <!-- 24px, flush with the card -->
</div>absolute and fixed elements are measured by their insets from the parent's padding edge, so rings and overlays need nothing either: absolute inset-1 inside a relative rounded-2xl border p-4 card is 16 - 1 - 4 = 11px.
Unequal padding
With px-4 py-2 the gap differs per axis. By default each corner uses the smaller gap and stays circular (24 - 8 = 16px). Add concentric-elliptical to subtract each axis' own gap instead (8px / 16px), which keeps the curve exactly parallel.
Minimum radius
Deep nesting or a large gap clamps the radius to 0. Set a floor on any ancestor:
<body class="[--concentric-floor:2px]">Pills
Children of rounded-full parents stay pills.
Squircles
With corner-shape: squircle, subtracting the gap once leaves the inner corner too round. Put concentric-squircle on the child: it sets corner-shape: squircle and scales the gap by 1.84, which keeps the gap even at the edges and the diagonal, and within 3% in between. Give the parent concentric-squircle (or [corner-shape:squircle]) as well. Browsers without corner-shape ignore both and keep round corners with the plain gap.
tailwind-merge
If you merge classes with tailwind-merge (for example in a cn() helper), register the plugin's classes so they replace radius classes instead of sitting next to them:
import { extendTailwindMerge } from "tailwind-merge";
import { withConcentric } from "tailwindcss-concentric/merge";
export const twMerge = extendTailwindMerge(withConcentric);
// with your own config: extendTailwindMerge({ ...yourConfig }, withConcentric)Without this, twMerge("rounded-lg", "rounded-concentric") keeps both and rounded-lg wins.
What the plugin reads
The radius comes from rounded-* classes on the nearest ancestor whose class contains rounded. The gap comes from Tailwind padding (p, px, py, ps, pe, pt, pr, pb, pl, pbs, pbe) and border-width (border, border-x, border-t, border-s, ...) classes on that ancestor and on the nearest wrapper in between, from margin classes (m, mx, -mt, ms, ...) on the child, and for absolute and fixed children from inset classes (inset, inset-x, top, start, ...). Arbitrary values (p-[10px], rounded-[20px]), CSS variables (p-(--space)), negative values and every variant work.
It does not see:
- a second padded wrapper on the same side, or margins on wrappers. Each side counts the nearest wrapper's padding and border only. Give the outer wrapper
rounded-concentrictoo: it joins the chain, passes everything inside it on, and has no visible effect unless it has a background, border oroverflow-hidden.rounded-concentric-{n}works as well; - padding or radii from inline styles or custom CSS, and
@applyin classes whose name does not containrounded. Use an explicit gap; - percentage radii (
rounded-[50%]). Fraction insets (inset-x-1/4) fall back to the parent's padding, andautomargins count as 0; - a containing block other than the rounded ancestor: insets are measured from the nearest rounded ancestor's padding edge, so a
relativewrapper in between throws them off; - corner shapes other than
squircle; - direction set only through CSS. Logical classes follow
dirattributes. Browsers with@scope(Chrome 118, Safari 17.4, Firefox 146) also followdir="auto"and any nesting depth; older ones read up to three nesteddirlevels.
Audit an existing codebase
The package includes a zero-dependency command that finds nested radii that do not match their parent:
npx tailwindcss-concentric audit # scans ./src, or the current folder
npx tailwindcss-concentric audit app components --jsonsrc/components/ProductCard.tsx:4:7 nested-radius
rounded-3xl renders 24px, but inside rounded-3xl p-2 on line 3 the concentric radius is 16px.
Use: rounded-concentricIt reads class attributes in HTML, JSX/TSX, Vue, Svelte and Astro files. It reports nested radii that are off, hard-coded calc() radii, absolute inset-* rings, wrappers the plugin cannot see (stacked or with margins), a tailwind-merge setup that is missing withConcentric, and a missing plugin import. It exits with 1 when it finds something, so it can run in CI.
It works from markup, not layout. It cannot tell whether a child really sits in its parent's corner, and it skips what it cannot evaluate: custom theme radii, CSS variables, variant classes, and class names passed between components. Put a comment containing concentric-ignore right before an element to silence it.
Debugging
Select the element in your browser's DevTools and run these in the console ($0 is the selected element):
getComputedStyle($0).borderTopLeftRadius // what renders
getComputedStyle($0).getPropertyValue("--cc-self-tl-x") // the concentric value; "" means the plugin is not loaded
$0.parentElement.closest('[class*="rounded"]') // the element it measures from| Symptom | Usual cause |
|---|---|
| Square corners everywhere, --cc-self-tl-x is "" | The plugin is not imported. Check the CSS file that imports Tailwind (npx tailwindcss-concentric audit reports this too). |
| The child keeps its old radius | cn() / twMerge kept both classes: extend tailwind-merge with withConcentric. |
| The child has the parent's full radius | The padding comes from inline styles or custom CSS. Use rounded-concentric-{n}. |
| The child is a little too round | A second padded wrapper or a wrapper margin sits in between. Give the outer wrapper rounded-concentric. |
| The child is square | The gap is at least the parent's radius. That is the correct result; set --concentric-floor if you want a minimum. |
| The radius is measured from the wrong element | A closer ancestor has rounded in its class (even md:rounded-lg). |
How it works
Each radius, padding, border, margin, inset and position utility also writes its value into non-inherited custom properties registered with @property. Every element whose class contains rounded is a level of a selector-based ladder (:where() rules, zero specificity) that copies the nearest rounded ancestor's values into two inherited slots that alternate by level. Wrappers without a radius pass their padding and border on through an inherited relay. Concentric classes read those values and compute the radius with calc() and max(). Elements that do not publish a radius pass the values through, so responsive classes like md:rounded-lg are safe.
The design and the browser experiments behind it are in DECISIONS.md.
Size. About 3.2 KB gzipped added to a minified app stylesheet: the @property rules and the ladder, plus the declarations of the utilities you use.
Browser support
Everything Tailwind CSS v4 supports: Chrome 111+, Safari 16.4+, Firefox 128+. Browsers with @scope (Chrome 118+, Safari 17.4+, Firefox 146+) also follow dir="auto" and direction changes at any depth, and browsers with corner-shape render concentric-squircle. The end-to-end suite renders every edge case in Chromium, WebKit and Firefox, with and without @scope, and compares computed radii.
Agent skill
The repository ships an agent skill at skills/concentric that teaches coding agents when to use these classes, when not to, and how to audit a codebase for mismatched nested radii.
License
MIT
