tailwindcss-anchors

Anchors for Tailwind CSS

Anchors for Tailwind CSS is a plugin that brings declarative support for the CSS Anchor Positioning API to Tailwind, allowing you to define and position elements relative to custom anchors. It adds utilities for anchor-name, position-anchor, position-area, anchor() and anchor-size() expressions.

It also lays the groundwork for using View Transitions to animate any anchored elements, which would require separate JS (for now 👀).

Installation

1. Install the plugin from npm with your preferred package manager:

   npm install -D tailwindcss-anchors

2. Then include it in your Tailwind CSS or JS config file:

   CSS (Tailwind CSS v4+)

   /* style.css */
   @import "@toolwind/anchors";

   JS (Tailwind CSS v3 compatible)

   // tailwind.config.js
   import anchors from "@toolwind/anchors";

Usage

Defining an anchor

Use the anchor/{name} utility to define an anchor point:

<div class="anchor/my-anchor"></div>

The CSS anchor-name property requires a dashed ident. For convenience, Anchors for Tailwind CSS automatically converts simple names into dashed idents.

For example, the above utility generates this CSS, prefixed with --tw-anchor_:

.anchor\/my-anchor {
  anchor-name: --tw-anchor_my-anchor;
}

If you need to use a specific dashed ident for an anchor name, the plugin will respect and preserve the original name if it encounters an ident that is already dashed.

<div class="anchor/--my-anchor"></div>

This utility also accepts arbitrary values, so if you want to pass a name via a CSS variable, you can do so using the square bracket syntax, like this:

<div class="[--custom-property:--my-anchor]">
  <div class="anchor/[var(--custom-property)]"></div>
</div>

🚧 Note that names passed via a custom property (square bracket syntax) resolves to a dashed ident already, as it's not possible for a plugin to read and manipulate runtime values.

Positioning relative to an anchor

Once an anchor has been defined, you can anchor other elements to it.

Use anchored/{name} to attach an element to an anchor:

<div class="anchored/my-anchor"></div>

Use anchored-{side} to specify the position area of the anchored element. For example, anchored-top-center will position the element at the top center of its anchor, touching the anchored element:

<div class="anchored-top-center"></div>

Or, put both together for shorthand syntax:

<div class="anchored-top-center/my-anchor"></div>

This sets:

position-anchor: --tw-anchor_my-anchor;
position-area: top center;
position: absolute;
view-transition-name: --tw-anchor-view-transition-313d192p322r2w3336;
/* ☝️ View Transition-ready, with encoded view-transition-name */

Both the position and view-transition-name are applied with zero specificity (via :where()), making them easy to overwrite with other values, if you choose. As a rule of thumb, anchored elements must use absolute or fixed positioning. This plugin defaults to absolute positioning, but you can add fixed to use fixed positioning instead.

This plugin strives to strike a balance between abstracting away the complexity of the CSS Anchor Positioning API and empowering developers to fully leverage it.

Supported Utilities

anchor/{name}

Sets anchor-name: --tw-anchor_{name}

anchored/{name}

Sets:

• position-anchor: --tw-anchor_{name}
• view-transition-name (automatically generated per anchor)

anchor-{position}

Sets position-area. Examples:

• anchor-top-center → top center
• anchor-bottom-span-left
• anchor-top-right, etc.

{top|right|bottom|left|inset}-anchor-{side}-{offset}/{name?}

Generates directional offset using anchor():

<div class="top-anchor-bottom"></div>

Results in:

top: anchor(bottom);

With offset support:

<div class="top-anchor-bottom-4"></div>

top: calc(anchor(bottom) + 1rem); // assuming 4 = theme('spacing.4')

{w|h}-anchor{-size?}/{name?}]

Size utilities using anchor-size():

• Omitting the anchor size (i.e. default size/dimension)

  w-anchor → width: anchor-size(width) If the {size} is omitted, the dimension defaults to the <anchor-size> keyterm that matches the axis of the property in which the function is included. For example, width: anchor-size(); is equivalent to width: anchor-size(width);. (source: MDN)

• Declaring the anchor-size (width/height/etc.) to use as a length

  w-anchor-height → width: anchor-size(height)

• Setting/omitting the anchor name

  • w-anchor → width: anchor-size(width)
  • w-anchor/--name → width: anchor-size(--name width)
  • w-anchor/name → width: anchor-size(--tw-anchor_name width)

  Specifying an <anchor-name> inside an anchor-size() function neither associates nor tethers an element to an anchor; it only defines which anchor the element's property values should be set relative to. (source: MDN)

View Transition API Integration

Every anchored/{name} class includes a view-transition-name, making your anchored elements animatable with document.startViewTransition():

document.startViewTransition(() => {
  el.classList.remove('anchor-top-left')
  el.classList.add('anchor-bottom-right')
})

This animates position shifts smoothly using the browser-native View Transitions API.

Why use Anchors for Tailwind CSS? 🤔

• Declarative anchor positioning with Tailwind utility syntax
• Full support for native anchor-related CSS properties and functions
• Easy offset control via calc(anchor(...) + theme spacing) (under the hood)
• Built-in support for View Transitions
• Fully JIT-compatible, no runtime required

Additional Resources 📚

• MDN: Guide: Using CSS anchor positioning | anchor-size() | anchor() | anchor-name | position-anchor | position-area | position-try-order
• CSS Tricks: CSS Anchor Positioning Guide
• Specification: CSS Anchor Positioning
• The Anchor Tool 👈 probably the best way to get a real fast introduction to the CSS Anchor Positioning API, how it works, and how helpful it can be ✨
• @Una! I've never met anyone more fired up about CSS Anchor Positioning than Una Kravets, so definitely check out some of the things she's posted about it. I'm not 100% certain, but I think she may have actually created the The Anchor Tool mentioned above.

Coming soon 👀🤞

Some relevant features that are not part of this plugin yet are:

• anchor-center
• position-try-order | position-try-fallbacks | position-try
• position-visibility

If you liked this plugin...

Check out more by @branmcconnell:

• tailwindcss-signals: React to parent or ancestor state
• tailwindcss-members: Style based on child/descendant state
• tailwindcss-mixins: Reusable, aliased groups of utilities
• tailwindcss-selector-patterns: Dynamic selector composition
• tailwindcss-directional-shadows: Shadows with directional awareness
• tailwindcss-default-shades: Simpler default color utility names
• tailwindcss-js: Effortless script injection
• tailwindcss-multi: Group utility declarations under variants
• tailwind-lerp-colors: Flexible color interpolation and palette tooling