tailwindcss-bg-images-plugin v1.1.3
DEPRECATED - PLEASE USE @olenzilla/tailwindcss-plugin-background-image INSTEAD
This repo is no longer being maintained; the package at https://github.com/olenzilla/tailwindcss-plugin-background-image is where development will continue.
tailwindcss-bg-images-plugin
A Tailwind plugin that generates background-image TailwindCSS utilities from glob'd pattern of image files.
Headline: when used in combination with Prettier and prettier-plugin-tailwindcss, this allows you to have autocompletion for the bg-* classes this plugin creates.
Basic Usage
This will use all default options:
- Find and create all images under
src - Create a Tailwind utility classes for each image with, and without, their respective file extensions. For example:
src/something.pngmeans you can useclass="bg-something"orclass="bg-something.png"in your HTML templates.- Those tailwind utilities will be styled as
background-image: url('src/something.png');
- Because these are just Tailwind utilities:
- You can use any variants enabled in your Tailwind config. For example:
- With images
src/home-mobile.jpgandsrc/home-desktop.jpg, - You can use
class="bg-home-mobile md:bg-home-desktop"to style a responsive home background image.
- With images
- By using Prettier and
prettier-plugin-tailwindcss, you will have autocomplete for all thebg-*Tailwind utilities this plugin creates.
- You can use any variants enabled in your Tailwind config. For example:
Contents of tailwind.config.js:
/** @type {import('tailwindcss').Config} */
module.exports = {
// ...
plugins: [
require('tailwindcss-bg-images-plugin'),
// ...
],
}Basic Nuxt Usage
If you're using Tailwind in a Nuxt project, use 'tailwindcss-bg-images-plugin/nuxt' in your tailwind.config.js. It is setup to assume you're using the assets folder for images, and uses a background-image expression of url('~/...') for the images there.
Contents of tailwind.config.js:
/** @type {import('tailwindcss').Config} */
module.exports = {
// ...
plugins: [
require('tailwindcss-bg-images-plugin/nuxt'),
// ...
],
}Advanced Usage
You can use:
/** @type {import('tailwindcss').Config} */
module.exports = {
// ...
plugins: [
require('tailwindcss-bg-images-plugin/make-plugin').default({
// ...
}),
// ...
],
}With any of the following options, to customize any aspect of this plugin for your particular project:
| Option | Type / Description | Default |
|---|---|---|
| globOptionsByPattern | Object whose keys are glob patterns, and whose values are the corresponding GlobOptions> for that glob pattern. | { './src/**/*.@(jpg|jpeg|png|gif|svg|webp)': { dot: true } } |
| makeStyle | function(imagePath: string): {backgroundImage: string} or false/null/undefined -- A function that takes the path of each image retrieved by the glob(s), and returns a dictionary for the background-image style of the created Tailwind utility. Or, if falsy, no utility will be created for that image. | (image) => ({ backgroundImage: `url('${image}')` }) |
| makeUtilityWithExtension | function(imagePath: string): string | false | null | undefined or false/null/undefined -- A function that takes the path of each image retrieved by the glob(s), and returns the name of the Tailwind utility to be created with the image's extension (to disambiguate it from another image with the same name but different extension). Or, if falsy, no utility will be created for image with its extension. | (image) => image.replace(/^src/, '') |
| makeUtilityWithoutExtension | function(imagePath: string): string | false | null | undefined or false/null/undefined -- A function that takes the path of each image retrieved by the glob(s), and returns the name of the Tailwind utility to be created without the image's extension. Or, if falsy, no utility will be created for image without the image's extension. | (image) => image.replace(/^src|\.\w+$/g, '') |
| utilityPrefix | string | false | null | undefined -- The string to be added as the prefix for all the utilities created by this plugin | 'bg-' |