@thiagormoreira/nightwind weekly downloads statistics

IMPORTANT: This repository is a maintained fork of the original "nightwind" project (https://github.com/jjranalli/nightwind). This fork is actively maintained, featuring 100% test coverage, support for modern Tailwind CSS (v3+), and additional features like manual dark: overrides.

---

A Tailwind CSS plugin that gives you an out-of-the-box, customisable, overridable dark mode.

---

Nightwind uses the existing Tailwind color palette and your own custom colors to automatically generate the dark mode version of the Tailwind color classes you use.

For example, whenever you use a class like bg-red-600 it gets automatically switched to bg-red-300 in dark mode.

You can see it in action on https://nightwindcss.com

1. Installation
2. Helper functions
3. Animation System
4. Getting started
5. Configuration
   • Colors
   • Variants and color classes
   • The 'nightwind-prevent' class
   • Transitions
   • Custom color scale
   • Important selector
6. Color mappings
   • Individual colors
   • Color classes
   • Hybrid mapping
7. Overrides
8. Typography
9. Tailwind CSS v4 Support

Installation

npm install nightwind

Enable the Dark class variant in your tailwind.config.js file.

// tailwind.config.js - Tailwind ^2.0
module.exports = {
  darkMode: "class",
  // ...
  plugins: [require("nightwind")],
}

In older Tailwind versions (< 2.0)

// tailwind.config.js
module.exports = {
  experimental: {
    darkModeVariant: true,
    applyComplexClasses: true,
  },
  dark: "class",
  // ...
  plugins: [require("nightwind")],
}

Helper functions

Nightwind relies on a fixed 'nightwind' class to manage transitions, and a toggled 'dark' class applied on a top level element in the DOM, typically the root element.

You can define your own functions to manage the dark mode (or check the examples below), or use the helper functions included in 'nightwind/helper.js' to get started right away.

By default, the helper functions prevent the dreaded flicker of light mode and allow the chosen color mode to persist on update.

Initialization

To initialize nightwind, add the following script tag to the head element of your pages.

// React Example
import nightwind from "nightwind/helper"

export default function Layout() {
  return (
    <>
      <Head>
        <script dangerouslySetInnerHTML={{ __html: nightwind.init() }} />
      </Head>
      // ...
    </>
  )
}

Toggle

Similarly, you can use the toggle function to switch between dark and light mode.

// React Example — toggle with animation
import nightwind from 'nightwind/helper'

export default function Navbar() {
  return (
    <>
      {/* Simple toggle with default animation */}
      <button onClick={() => nightwind.toggle()}>Toggle</button>

      {/* Ripple from click point */}
      <button onClick={(e) => nightwind.toggle({ animation: 'ripple', event: e })}>
        Ripple Toggle
      </button>

      {/* Slide from left */}
      <button onClick={() => nightwind.toggle({ animation: 'slide', direction: 'left' })}>
        Slide Toggle
      </button>
    </>
  )
}

Enable mode

If you need to selectively choose between light/dark mode, you can use the enable function. It accepts a boolean argument to enable/disable dark mode.

// React Example
import nightwind from "nightwind/helper"

export default function Navbar() {
  return (
    // ...
    <button onClick={() => nightwind.enable(true)}></button>
    // ...
  )
}

BeforeTransition

Nightwind also exports a beforeTransition function that you can leverage in case you prefer to build your own toggle functions. It prevents unwanted transitions as a side-effect of having nightwind [...]

Check out the toggle function in the Nextjs example below for an example of how this could be implemented.

Animation System

Nightwind includes a built-in animation system powered by the View Transitions API. All animations fall back gracefully to a CSS transition for browsers that don't support the API.

Global Configuration

Configure the animation system once via nightwind.configure():

nightwind.configure({
  animation: {
    default: 'fade',              // Default animation for toggle/enable
    duration: 600,                // Duration in ms
    easing: 'cubic-bezier(0.7, 0, 0.3, 1)', // CSS easing or cubic-bezier
    reverse: false,               // Reverse direction on light mode
    slide: {
      direction: 'left',          // 'left' | 'right' | 'top' | 'bottom'
    },
  },
  transition: {
    duration: 400,                // CSS transition duration (ms)
    easing: 'ease-in-out',
  },
  persistence: true,              // Persist mode in localStorage
  storageKey: 'nightwind-mode',   // localStorage key
})

Per-call Options

Any option can be overridden per call:

// Use ripple just for this click
nightwind.toggle({ animation: 'ripple', event: e })

// Slide from top with custom duration
nightwind.toggle({ animation: 'slide', direction: 'top', duration: 400 })

// Disable animation for this call
nightwind.enable(true, { animation: 'none' })

Available Animations…