tailwindcss-intersect

Version 3 requires Tailwind CSS v4. If you are using Tailwind CSS v3, continue using the 2.x releases.

In version 3, the Observer has moved to a dedicated entry point. You must update your import path:

Old: import { Observer } from 'tailwindcss-intersect';

New: import { Observer } from 'tailwindcss-intersect/observer';

The plugin requires a JavaScript snippet to run the IntersectionObserver logic. You can include it via CDN or import it into your JS bundle.

Via CDN: Include this script tag in your HTML:

<script defer src="https://unpkg.com/tailwindcss-intersect@3.x.x/dist/observer.min.js"></script>

Via NPM (Recommended for bundles): Import the Observer and call .start(). If you are building a Single Page Application (SPA), call Observer.restart() on route changes to ensure elements on the new route are observed.

import { Observer } from 'tailwindcss-intersect/observer';

Observer.start();

If you are using @apply to define custom classes, you must add the intersect class to the HTML element to signal the observer to watch it.

<div class="intersect custom-class"></div>

Depending on your setup, register the plugin in your CSS file or your Tailwind configuration file.

Using CSS imports (Tailwind CSS v4):

@import "tailwindcss";
@import "tailwindcss-intersect";

Using a JavaScript configuration file:

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require('tailwindcss-intersect')
  ],
}

Elements that are already visible on page load may not trigger their intersect: styles because the observer runs after the initial render. To force the animation/style to apply to elements already in view, add the no-intersect attribute.

<div class="opacity-0 intersect:opacity-100 transition-opacity" no-intersect></div>

Install the package via npm to get both the Tailwind CSS plugin and the JavaScript observer utility.

npm install tailwindcss-intersect

The Observer class manages the lifecycle of elements using the following logic:

1. State Tracking: When an element enters the viewport (based on its threshold and margin), the no-intersect attribute is removed from the element.
2. Out of View: When an element leaves the viewport, the no-intersect attribute is added to the element.
3. One-time Observation: If an element has the intersect-once class, the observer will automatically disconnect from that specific element after its first intersection event, preventing further state changes.

This allows you to style elements based on their visibility using CSS selectors like [no-intersect] or by targeting the presence/absence of the attribute.

To use the intersection modifiers, add the tailwindcss-intersect plugin to your tailwind.config.js file. The plugin registers a single variant, intersect, which applies styles only when the element does not have the no-intersect attribute.

// tailwind.config.js
const intersectPlugin = require('tailwindcss-intersect')

module.exports = {
  // ...
  plugins: [
    intersectPlugin,
  ],
}

Apply styles that trigger only when an element enters the viewport using the intersect: variant.

<div class="bg-cyan-500 intersect:bg-indigo-600 transition-colors"></div>

To begin observing elements with intersect: utility classes, call Observer.start(). This method ensures the DOM is fully loaded before attempting to find and observe elements. If the document is still in the loading state, it waits for the DOMContentLoaded event before executing.

import { Observer } from 'tailwindcss-intersect';

Observer.start();

If you dynamically add new elements to the DOM that use intersection utility classes, or if you need to reset the current state, call Observer.restart(). This method disconnects all existing IntersectionObserver instances, clears the internal observer registry, and re-scans the document for all elements matching the intersection selectors.

import { Observer } from 'tailwindcss-intersect';

// Call this after injecting new HTML content to ensure new elements are observed
Observer.restart();