Usage

The Active Breakpoint helper adds a small indicator of the active breakpoint to your page. This is helpful when you're developing or debugging, and need to know what breakpoint you're looking at.

Note that the active breakpoint helper does not appear on production sites, which is denoted by a process.env.NODE_ENV value of production. This is the same value Tailwind uses to determine whether to turn on PurgeCSS, so you should have set it up already.

We've replicated it on this page so that you can see it in action.

See customization options for more information on customizing the styles added, or disabling it completely.

Customizing

Screens

You can customize which breakpoints the helper will display. You can do this with an allow list called screens, a block list called ignoreScreens, or both.

Allow List

To create an allow list of screens to display, specify the screen names using the screens option in the theme.activeBreakpoint section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
+   activeBreakpoint: {
+     screens: ['md', 'lg'],
+   },
  },
}

This property will default to Tailwind's screens object if left unspecified.

Block List

It may be easier to specify a block list instead. This will ignore any screens specified, even if they're added in the screens object.

To create a block list of screens to not display, specify the screen names using the ignoreScreens option in the theme.activeBreakpoint section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
+     activeBreakpoint: {
+       ignoreScreens: ['sm', '2xl'],
+     },
    },
  },
};

This property will default to an empty array. This property can be useful if you're using tweakpoints for specific cases or components, and do not need to see them in the active breakpoint helper.

If both screens and ignoreScreens are not added to your config, the active breakpoint helper will show all screens defined in your Tailwind config.

Position

You can choose the corner of the screen that the active breakpoint helper will display in.

To choose the corner, a prefix or suffix, specify horizontal and vertical position using the position option in the theme.activeBreakpoint section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
+     activeBreakpoint: {
+       position: ['top', 'right'],
+     },
    },
  },
};

The available options are: ['top', 'left'], ['top', 'right'], ['bottom', 'left'] or ['bottom', 'right'],

Prefix + Suffix

The helper can display a prefix and a suffix before and after the text on the active breakpoint helper.

By default, these are both empty.

To create a prefix or suffix, specify the text using the prefix or suffix option in the theme.activeBreakpoint section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
+     activeBreakpoint: {
+       prefix: 'screen: ',
+       suffix: ' 🔥',
+     },
    },
  },
};

You may specify both, one or the other, or neither, in your config.

Changing entire text

You may also change the text displayed on the helper at any and all breakpoints.

To do this, you'll need to change the content style rule on the body::before class, for each screen, using the @screen directive:

body::before {
  content: 'No breakpoint';
}

@screen sm {
  body::before {
    content: 'screen: sm';
  }
}

...

When doing it this way, apply any prefixes or suffixes directly in your css, as it will no longer use the ones written in your tailwind config.

If you've changed the pseudo element or the class name in your tailwind.config.js, you'll need to use the changes here as well. For more info see the using a class name section.

Styles

You can add styles to the active breakpoint helper if you would like in several ways.

Tailwind Config

The simplest way would be straight in your tailwind.config.js file, by specifying the styles using the styles option in the theme.activeBreakpoint section:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      activeBreakpoint: (theme) => ({
+       styles: {
+         backgroundColor: theme('colors.indigo.500'),
+       },
      }),
    },
  },
}

The styles object is merged into the main styles of the active-breakpoint, applied to body::before, and will override any defaults set by Captain. Therefore, any CSS-in-JS can be used here.

Components / CSS

Alternatively, you can style body::before directly in your css, or in a component.

Target the body::before selector and add any styles you need.

body::before {
  background-color: theme('colors.indigo.500');
}

Using a class name

The active breakpoint helper targets body::before by default.

However, you may wish to use body::after, or even a different element entirely, to avoid conflicts with other code.

You can specify which selector and pseudo class to apply using the selector and pseudo options in the theme.activeBreakpoint section of your config file:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      activeBreakpoint: {
+       pseudo: 'after', // This will now use `body::after`
      }),
    },
  },
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      activeBreakpoint: {
+       selector: '.active-breakpoint', // This will now use `.active-breakpoint::before`
      }),
    },
  },
}

If using a class, make sure you include the . to designate it as a class. You'll also need to add this class to an element in your HTML for it to apply.

If you're using a Tailwind prefix it will be automatically applied to your selector if it is a class.

Variants

By default, no variants are generated for the active breakpoint helper.

You can control which variants are generated for the active breakpoint helper by modifying the activeBreakpoint property in the variants section of your tailwind.config.js file.

  // tailwind.config.js
  module.exports = {
    variants: {
      // ...
+     activeBreakpoint: [],
    }
  }

Disabling entirely

If you don't plan to use the active breakpoint utilities in your project, you can disable them entirely by setting the activeBreakpoint property to false in the captain.plugins section of your config file:

  // tailwind.config.js
  module.exports = {
    captain: {
      plugins: {
        // ...
+       activeBreakpoint: false,
      }
    }
  }