Tailwind CSS Plugin for Declarative CSS Anchor Positioning

The Anchors for Tailwind plugin adds declarative support for the CSS Anchor Positioning API to Tailwind CSS.

It wraps native CSS properties such as anchor-name, position-anchor, position-area, anchor(), and anchor-size() in Tailwind’s familiar utility syntax.

This approach maintains the full power of CSS anchor positioning while providing the convenience and consistency that Tailwind CSS developers expect.

The TailwindCSS plugin allows you to connect an element to an anchor and then specify its position, such as top-center or bottom-left.

It also includes features for creating fallback positions to prevent elements from overflowing the viewport and for controlling visibility.

Features

Installation

1. Install the plugin with NPM

npm install -D @toolwind/anchors

2. Include the plugin in your Tailwind CSS configuration:

Tailwind CSS v4+

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

Tailwind CSS v3

// tailwind.config.js
import anchors from "@toolwind/anchors";
export default {
  plugins: [anchors],
  // ... rest of your config
};

Usage

1. Create anchor points using the anchor/{name} utility. The plugin automatically handles CSS anchor-name requirements by converting simple identifiers to dashed identifiers:

<!-- Simple identifier (recommended) -->
<button class="anchor/my-button">Click me</button>
<!-- Dashed identifier -->
<button class="anchor/--my-button">Click me</button>
<!-- Arbitrary value with CSS variable -->
<div class="[--btn:--my-button]">
  <button class="anchor/[var(--btn)]">Click me</button>
</div>

2. Once you have defined an anchor, position other elements relative to it using positioning utilities:

<!-- Anchor an element to a named anchor -->
<div class="anchored/my-button"></div>
<!-- Position relative to the anchored element -->
<div class="anchored-top-center"></div>
<!-- Combine anchoring and positioning -->
<div class="anchored-top-center/my-button"></div>

3. Use directional positioning utilities for precise control over element placement:

<!-- Position using anchor() function -->
<div class="top-anchor-bottom left-anchor-right"></div>
<!-- Add spacing offsets -->
<div class="top-anchor-bottom-4 left-anchor-left-2"></div>

4. Set element dimensions based on anchor element sizes:

<!-- Match anchor width -->
<div class="w-anchor"></div>
<!-- Set width to anchor height -->
<div class="w-anchor-height"></div>
<!-- Reference specific anchor -->
<div class="w-anchor/my-button h-anchor-height/my-button"></div>

5. Control when anchored elements appear and provide fallback positioning:

<!-- Show only when anchor is visible -->
<div class="anchored-visible-anchor"></div>
<!-- Hide when element would overflow viewport -->
<div class="anchored-visible-no-overflow"></div>
<!-- Provide fallback positions -->
<div class="try-flip-all try-order-normal"></div>

All Available Utilities

• anchor/{name}: Sets the anchor-name property to define an element as an anchor point for other elements to position themselves against.
• anchored/{name}: Sets the position-anchor property to link an element to a specified anchor.
• anchored-{position}: Sets the position-area property to place the element relative to its anchor, for example, anchored-top-center.
• {top|right|bottom|left|inset}-anchor-{side}-{offset}/{name?}: Applies explicit directional positioning using the anchor() function, with optional offsets. For instance, top-anchor-bottom-4 calculates top: calc(anchor(bottom) + 1rem).
• {w|h}-anchor{-size?}/{name?}: Adjusts the width or height of an element using the anchor-size() function, allowing its dimensions to be based on its anchor’s size.
• anchored-visible-*: Controls the element’s visibility with the position-visibility property. Options include anchored-visible-always, anchored-visible-anchor, and anchored-visible-no-overflow.
• try-order-*: Sets the position-try-order property to define the priority for fallback positions, such as maximizing width or height within the viewport.
• try-*: Defines fallback positioning strategies using position-try-fallbacks. Utilities include try-flip-x and try-flip-y to adjust the element’s position to keep it in view.

Related Resources

• CSS Anchor Positioning Specification: The official W3C specification that defines the CSS Anchor Positioning API and its properties. View Specification
• The Anchor Tool: An interactive tool for learning and experimenting with CSS anchor positioning concepts and syntax. Try The Anchor Tool
• Tailwind CSS Official Documentation: Complete documentation for Tailwind CSS framework, including plugin development guidelines. Visit Tailwind CSS Docs
• MDN CSS Anchor Positioning Guide: Detailed guide covering CSS anchor positioning usage, properties, and browser support information. Read MDN Guide

FAQs

Q: What is CSS Anchor Positioning?
A: It is a CSS API that lets you position an element relative to one or more other elements, called anchors, on the page without JavaScript.

Q: Does this plugin require a JavaScript runtime?
A: No, the plugin is JIT-compatible and does not need any runtime JavaScript. It generates utility classes that map to native CSS properties.

Q: Can I override the default positioning?
A: Yes. The plugin uses :where() to apply position: absolute with zero specificity. You can override this by adding a class like fixed to the anchored element.

Q: Do anchored elements require specific positioning values?
A: Anchored elements must use absolute or fixed positioning to work correctly. The plugin automatically applies position: absolute with zero specificity, which you can override with fixed if needed.

Q: How do fallback positions work when anchors are off-screen?
A: The try-* utilities define fallback positions that the browser attempts when the primary position would cause overflow or poor visibility. The browser automatically selects the best available fallback based on viewport constraints.

Q: Can I animate position changes between anchor positions?
A: Yes, the plugin includes built-in View Transition API integration. Each anchored element receives a unique view-transition-name, allowing you to use document.startViewTransition() for smooth position animations.