Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/toolwind/anchors/llms.txt

Use this file to discover all available pages before exploring further.

This page covers what changes when moving between Tailwind CSS versions with @toolwind/anchors, as well as any breaking changes introduced in the plugin itself. The plugin supports Tailwind v3 and v4 simultaneously — but the two versions have meaningful syntax differences that affect how some utility classes behave.
@toolwind/anchors declares a peer dependency of tailwindcss >= 3.0.0 || >= 4.0.0. You do not need separate installs for different Tailwind versions — the same package adapts its behavior at runtime based on which version of Tailwind is running.

​
Differences between Tailwind v3 and v4

​
1. Import method

How you register the plugin differs between versions.
In v4, plugins are registered via a CSS @import statement in your main stylesheet.
/* style.css */
@import "@toolwind/anchors";

​
2. Variable shorthand syntax

Both versions support a shorthand for referencing CSS custom properties as anchor names, but the delimiter character differs.
In v4, use parentheses for the variable shorthand: anchor/(--x)
<!-- These two are equivalent in v4 — both produce anchor-name: var(--x) -->
<div class="anchor/(--x)"></div>
<div class="anchor/[var(--x)]"></div>

/* output */
.anchor\/\(--x\) {
  anchor-name: var(--x);
}

​
3. Arbitrary bracket syntax — a common gotcha

The meaning of anchor/[--my-anchor] changed between Tailwind v3 and v4. In v3 it produces anchor-name: var(--my-anchor). In v4 it produces anchor-name: --my-anchor (the dashed ident itself). This is the most common source of confusion when migrating between versions.
In Tailwind v3, square brackets were used for both arbitrary values and variable shorthand. A value like [--my-anchor] was interpreted as variable shorthand — it expanded to var(--my-anchor). In Tailwind v4, parentheses handle variable shorthand exclusively, so [--my-anchor] is treated as an arbitrary value and the dashed ident is used directly, without wrapping in var(). 
<!-- v4: [--my-anchor] passes the dashed ident directly -->
<div class="anchor/[--my-anchor]"></div>

/* output in v4 */
.anchor\/\[--my-anchor\] {
  anchor-name: --my-anchor;
}
To reference the variable’s value in v4, use parentheses:
<div class="anchor/(--my-anchor)"></div>

/* output in v4 */
.anchor\/\(--my-anchor\) {
  anchor-name: var(--my-anchor);
}

​
Equivalent expressions cheat sheet

IntentTailwind v4Tailwind v3
Plain ident (auto-prefixed)anchor/my-nameanchor/my-name
Dashed ident directlyanchor/--my-nameanchor/--my-name
Dashed ident via arbitraryanchor/[--my-name](not the same — see above)
Reference CSS variableanchor/(--x)anchor/[--x]
Full var() arbitraryanchor/[var(--x)]anchor/[var(--x)]

​
Changes in @toolwind/anchors itself

The current release is v1.0.10. The plugin’s public API has been stable since initial release. No utility names have been renamed or removed across patch versions. The most significant internal change was adding first-class detection of the Tailwind version at runtime (v3 vs. v4) to handle the syntax differences described above. If you are upgrading from a pre-1.0 version, review the README for any notes specific to that transition, as early pre-release builds may have used different class name patterns.
If you accidentally use the v4-only parenthesis shorthand syntax (e.g. anchor/(--x)) in a Tailwind v3 project, the plugin throws an error at build time with a message explaining the issue and pointing you to the correct v3 equivalent (anchor/[--x]).

​
Further reading

Build docs developers (and LLMs) love

Get started for freeTalk to us