[bug] box-shadow doesn't work in shadow-dom due to reliance on @property

[snaptopixel]

What version of Tailwind CSS are you using?

v4.0.6

What build tool (or framework if it abstracts the build tool) are you using?

tailwind-cli

What version of Node.js are you using?

v20.0.0

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://codepen.io/snaptopixel/pen/GgRZebj

Describe your issue

Tailwind's box-shadow based utils (ring, shadow, etc) use multiple shadow syntax with custom properties:

box-shadow: var(--foo), var(--bar), var(--baz);

Since these vars don't have default/fallback values the whole box-shadow breaks if any one of them is undefined. In non-shadow this is a non-issue since @property provides default values. However in shadow-dom @property does nothing, so ironically, in shadow-dom you will have no shadows on your dom.

Essentially it seems there should be suitable fallbacks for any utils that currently rely on @property since it doesn't work in shadow-dom land.

[philipp-spiess]

Hey @snaptopixel! Unfortunately @property declarations do not do anything when attached within a shadow-root, you need to ensue these are attached to the root document instead. We have an issue about this open at: #15005

The issue is that we rely on @property to make variables animatable and avoid inheritance, so using @property is a requirement for v4 unfortunately.

[snaptopixel]

Thanks @philipp-spiess, I'm curious why tailwind 4 made the design decision to rely on @property I don't think there is any required reason to use it over default variables? Is it just a convenience or "shiny new thing" feature? Looking at the other post it seems others have faced the same issue and frustration as I have. I would suggest a hard look at what it would take to refactor and be @property free unless it's absolutely a requirement for some reason.

[philipp-spiess]

@snaptopixel I don't think there is any required reason to use it over default variables?

@property allows us to control the inheritance properties of CSS variables and allows us to makes css variables interpolatable (read: animateable) by having a type (e.g. it would not be possible at all to animate box-shadow in Tailwind CSS without the use of @property).

I understand your frustration with how this feature works inside shadow-roots that makes it a bit inconvenient, but it's unfortunately specced like this. You can see more context on it here, for example: w3c/css-houdini-drafts#939 If you hoist the @property declarations into the document root styles, it will work as expected.

[snaptopixel]

Thanks for the discussion, appreciated! How would one hoist @property declarations? Is there a way to output css with only the @Property declarations via the CLI? For reference, I'm building a single tailwind css file and using it in shadow-dom web components via <link> tag. I really don't want anything bleeding out into the page. For now I'm stuck adding my own defaults under the :host selector as I run across issues which is less than ideal.

[snaptopixel]

For reference here's what I'm using to list of all the @property vars that have initial-value in my shadow-dom

:host {
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-translate-z: 0;
  --tw-rotate-x: rotateX(0);
  --tw-rotate-y: rotateY(0);
  --tw-rotate-z: rotateZ(0);
  --tw-skew-x: skewX(0);
  --tw-skew-y: skewY(0);
  --tw-border-style: solid;
  --tw-gradient-from: #0000;
  --tw-gradient-via: #0000;
  --tw-gradient-to: #0000;
  --tw-gradient-from-position: 0%;
  --tw-gradient-via-position: 50%;
  --tw-gradient-to-position: 100%;
  --tw-shadow: 0 0 #0000;
  --tw-inset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-inset-ring-shadow: 0 0 #0000;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-outline-style: solid;
}

[Gregory-Gerard]

Here's a complete reference of all Tailwind v4 CSS custom properties with their initial values (extracted from the source code as of October 2025). This is also compatible with tw-animate-css.

Do not use just :host for these declarations. If you only apply them to :host and add a .shadow class on a parent element, all children with rings, shadows, or other effects will inherit those values, causing unwanted side effects, because CSS variables are inherited, *, ::before, ::after prevent that (in part).

But, even with *, ::before, ::after, certain properties require @property declarations to work correctly. Without these type declarations:

• Line height variables (--tw-leading) will inherit incorrectly
• Transitions and animations won't interpolate properly (of course)

But as far as I can see, with this code, everything works pretty well. In my case, I couldn't use the technique of injecting @property declarations into the host page HTML (outside the shadow root) because it breaks existing applications that use Tailwind v3. The typed @property declarations from Tailwind v4 are fundamentally incompatible with v3's untyped CSS variables.

*, ::before, ::after {
  --tw-duration: 150ms;
  --tw-animation-delay: 0s;
  --tw-animation-direction: normal;
  --tw-animation-fill-mode: none;
  --tw-animation-iteration-count: 1;
  --tw-enter-blur: 0;
  --tw-enter-opacity: 1;
  --tw-enter-rotate: 0;
  --tw-enter-scale: 1;
  --tw-enter-translate-x: 0;
  --tw-enter-translate-y: 0;
  --tw-exit-blur: 0;
  --tw-exit-opacity: 1;
  --tw-exit-rotate: 0;
  --tw-exit-scale: 1;
  --tw-exit-translate-x: 0;
  --tw-exit-translate-y: 0;

  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-translate-z: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-scale-z: 1;
  --tw-scroll-snap-strictness: proximity;
  --tw-space-x-reverse: 0;
  --tw-space-y-reverse: 0;
  --tw-border-style: solid;
  --tw-divide-x-reverse: 0;
  --tw-divide-y-reverse: 0;
  --tw-gradient-from: #0000;
  --tw-gradient-via: #0000;
  --tw-gradient-to: #0000;
  --tw-gradient-from-position: 0%;
  --tw-gradient-via-position: 50%;
  --tw-gradient-to-position: 100%;
  --tw-mask-linear: linear-gradient(#fff, #fff);
  --tw-mask-radial: linear-gradient(#fff, #fff);
  --tw-mask-conic: linear-gradient(#fff, #fff);
  --tw-mask-left: linear-gradient(#fff, #fff);
  --tw-mask-right: linear-gradient(#fff, #fff);
  --tw-mask-bottom: linear-gradient(#fff, #fff);
  --tw-mask-top: linear-gradient(#fff, #fff);
  --tw-mask-linear-position: 0deg;
  --tw-mask-linear-from-position: 0%;
  --tw-mask-linear-to-position: 100%;
  --tw-mask-linear-from-color: black;
  --tw-mask-linear-to-color: transparent;
  --tw-mask-radial-from-position: 0%;
  --tw-mask-radial-to-position: 100%;
  --tw-mask-radial-from-color: black;
  --tw-mask-radial-to-color: transparent;
  --tw-mask-radial-shape: ellipse;
  --tw-mask-radial-size: farthest-corner;
  --tw-mask-radial-position: center;
  --tw-mask-conic-position: 0deg;
  --tw-mask-conic-from-position: 0%;
  --tw-mask-conic-to-position: 100%;
  --tw-mask-conic-from-color: black;
  --tw-mask-conic-to-color: transparent;
  --tw-drop-shadow-alpha: 100%;
  --tw-content: "";
  --tw-outline-style: solid;
  --tw-text-shadow-alpha: 100%;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-alpha: 100%;
  --tw-inset-shadow: 0 0 #0000;
  --tw-inset-shadow-alpha: 100%;
  --tw-ring-shadow: 0 0 #0000;
  --tw-inset-ring-shadow: 0 0 #0000;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-offset-shadow: 0 0 #0000;
}

[robustadev]

Hi, Just started a new project and found this discussion.
Like @snaptopixel did with the manual css custom properties injected into the host, I've created a PostCSS plugin that dees it automatically.

The plugin looks for @property declarations inside the css and convert them into a css custom property with the initial value from the @property

I guess i'll see some errors when it comes to animations since the css rules will not have an initial value to animate from.

Anyway, here is the Plugin code:

/**
 * PostCSS plugin to convert @property declarations to CSS custom properties
 * This helps with using property values inside Shadow DOM
 */
export default (opts = {}) => {
  return {
    postcssPlugin: 'postcss-property-to-custom-prop',
    prepare(result) {
      // Store all the properties we find
      const properties = [];

      return {
        AtRule: {
          property: (rule) => {
            // Extract the property name and initial value
            const propertyName = rule.params.match(/--[\w-]+/)?.[0];
            let initialValue = '';

            rule.walkDecls('initial-value', (decl) => {
              initialValue = decl.value;
            });

            if (propertyName && initialValue) {
              // Store the property
              properties.push({ name: propertyName, value: initialValue });

              // Remove the original @property rule
              rule.remove();
            }
          },
        },

        OnceExit(root, { Rule, Declaration }) {
          // If we found properties, add them to :root, :host
          if (properties.length > 0) {
            // Create the :root, :host rule using the Rule constructor from helpers
            const rootRule = new Rule({ selector: ':root, :host' });

            // Add all properties as declarations
            properties.forEach((prop) => {
              // Create a new declaration for each property
              const decl = new Declaration({
                prop: prop.name,
                value: prop.value,
              });
              rootRule.append(decl);
            });

            // Add the rule to the beginning of the CSS
            root.prepend(rootRule);
          }
        },
      };
    },
  };
};

export const postcss = true;

Usage:

import propertyToCustomProp from './plugins/postcss-property-to-custom-prop';
import tailwindcss from '@tailwindcss/postcss';

export default {
  plugins: [
    tailwindcss(),
    propertyToCustomProp()
  ],
};

Inside my web component i'm using the !inline directive for import and using the this.shadowRoot!.adoptedStyleSheets(...) like this:

import globalCss from '@/styles/global.css?inline';

const sheet = new CSSStyleSheet();
sheet.replaceSync(globalCss);

export class MyComponent extends HTMLElement {
    constructor() {
        super();

        this.attachShadow({ mode: 'open' });
        this.shadowRoot!.adoptedStyleSheets = [sheet];

        // ...
    }
}

[sschultze]

I stumbled upon this too. The decision to go for @property makes Tailwind 4 unusable for the Shadow DOM, which is very frustrating. If @property is really needed for something like animating drop shadows (it this so important?), then the developers should at least have included a configuration setting that makes something as simple as a drop shadow work in the Shadow DOM. In my opinion.

[rikgirbes]

Is there an update to this?
I really dislike having to use some kind of "hack".
@sschultze is right, there should be a configuration setting.

Same for :root / :host

[benkissi]

Working on an app thats going to be used as a widget on other 3rd party websites hence I need to use the shadow dom and then realised some variables are not defined. Spent some time debugging and then found this, can there be an opt in. I guess I will have to handroll my css

[rikgirbes]

@benkissi as you can read, I had the same issue, i fixed it by converting the @property declarations to custom css properties in postcss (credit: see @robustadev above)
This should be drop-in for you (postcss.config.js):

import tailwindcss from '@tailwindcss/postcss';
import autoprefixer from 'autoprefixer';

/**
 * PostCSS plugin to convert @property declarations to CSS custom properties
 */
const property_to_custom_prop = () => ({
	postcssPlugin: 'postcss-property-to-custom-prop',
	prepare() {
		const properties = [];

		return {
			AtRule: {
				property: (rule) => {
					const property_name = rule.params.match(/--[\w-]+/)?.[0];
					let initial_value = '';

					rule.walkDecls('initial-value', (decl) => {
						initial_value = decl.value;
					});

					if (property_name && initial_value) {
						properties.push({ name: property_name, value: initial_value });
						rule.remove();
					}
				},
			},
			OnceExit(root, { Rule, Declaration }) {
				if (properties.length > 0) {
					const root_rule = new Rule({ selector: ':root, :host' });

					for (const prop of properties) {
						root_rule.append(
							new Declaration({
								prop: prop.name,
								value: prop.value,
							}),
						);
					}

					root.prepend(root_rule);
				}
			},
		};
	},
});

property_to_custom_prop.postcss = true;

export default {
	plugins: [tailwindcss(), autoprefixer(), property_to_custom_prop()],
};

[BarrySong97]

i just faced the problem, don't want to add postcss.
just copy the properties var to your css file, don' struggle with it.

[web-engineer]

OK - I had same problem, but I needed this as a module. Also didn't want top copy properties over as the project is evolving and I want this to manage itself... What I found was the colour calculations were not working in shadow-dom and they needed to be simplified so I added a utility to convert these to RGBA and now my shadows are working nicely, this builds on @rikgirbes code and makes it adapt any shadows your using into css that shadow dom should be happy with.

/**
 * PostCSS plugin to convert @property declarations to CSS custom properties
 * AND fix shadow utilities for Shadow DOM compatibility
 */
const property_to_custom_prop = () => ({
	postcssPlugin: 'postcss-property-to-custom-prop',
	prepare() {
		const properties = [];
		let shadowsProcessed = 0;

		return {
			AtRule: {
				property: (rule) => {
					const property_name = rule.params.match(/--[\w-]+/)?.[0];
					let initial_value = '';

					rule.walkDecls('initial-value', (decl) => {
						initial_value = decl.value;
					});

					if (property_name && initial_value) {
						properties.push({ name: property_name, value: initial_value });
						rule.remove();
					}
				},
			},
			Rule(rule) {
				// Fix shadow utilities for Shadow DOM compatibility
				if (rule.selector.includes('shadow-')) {
					rule.walkDecls((decl) => {
						// Convert complex Tailwind shadow variables to direct values
						if (decl.prop === 'box-shadow' && (decl.value.includes('var(--tw-') || decl.value.includes('oklab('))) {
							// Handle direct oklab values in box-shadow (when not using variables)
							if (decl.value.includes('oklab(') && !decl.value.includes('var(--tw-')) {
								let shadowValue = decl.value;

								// Convert NEW oklab(from rgb()) patterns directly in box-shadow
								shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\s+l\s+a\s+b\s*\/\s*(\d+)%\)\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
									const alpha = (parseFloat(percentAlpha) / 100);
									return `rgba(${r}, ${g}, ${b}, ${alpha})`;
								});

								shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
									const alpha = (parseFloat(percentAlpha) / 100);
									return `rgba(${r}, ${g}, ${b}, ${alpha})`;
								});

								shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\)/g, (match, r, g, b, alpha) => {
									return `rgba(${r}, ${g}, ${b}, ${alpha})`;
								});

								shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, percentAlpha) => {
									const alpha = (parseFloat(percentAlpha) / 100);
									return `rgba(${r}, ${g}, ${b}, ${alpha})`;
								});

								decl.value = shadowValue;
								shadowsProcessed++;

								if (process.env.NODE_ENV !== 'production') {
									console.log(`🔧 PostCSS: Fixed direct shadow ${rule.selector} -> ${shadowValue}`);
								}
								return; // Don't process further if we handled direct values
							}
							// Extract shadow from --tw-shadow variable if present
							const shadowMatch = decl.value.match(/var\(--tw-shadow\)/);
							if (shadowMatch) {
								// Find the --tw-shadow declaration in the same rule
								rule.walkDecls('--tw-shadow', (shadowDecl) => {
									// Convert all shadow values dynamically
									let shadowValue = shadowDecl.value;

									// NEW: Convert oklab(from rgb()) patterns - Tailwind CSS 4 format
									// Handle: oklab(from rgb(0 0 0 / 0.1 l a b / 30%))
									shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\s+l\s+a\s+b\s*\/\s*(\d+)%\)\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
										const alpha = (parseFloat(percentAlpha) / 100);
										return `rgba(${r}, ${g}, ${b}, ${alpha})`;
									});

									// Handle: oklab(from rgb(0 0 0 / 0.1) l a b / 30%)
									shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
										const alpha = (parseFloat(percentAlpha) / 100);
										return `rgba(${r}, ${g}, ${b}, ${alpha})`;
									});

									// Handle: oklab(from rgb(0 0 0 / 0.1) l a b)
									shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\)/g, (match, r, g, b, alpha) => {
										return `rgba(${r}, ${g}, ${b}, ${alpha})`;
									});

									// Handle: oklab(from rgb(0 0 0) l a b / 30%)
									shadowValue = shadowValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, percentAlpha) => {
										const alpha = (parseFloat(percentAlpha) / 100);
										return `rgba(${r}, ${g}, ${b}, ${alpha})`;
									});

									// Convert oklab patterns - extract alpha from oklab(0% 0 0/ALPHA)
									shadowValue = shadowValue.replace(/oklab\(0% 0 0\/\.(\d+)\)/g, (match, alpha) => {
										const alphaValue = parseFloat('0.' + alpha);
										return `rgba(0, 0, 0, ${alphaValue})`;
									});

									// Convert oklab patterns with decimal alpha - oklab(0% 0 0/.05)
									shadowValue = shadowValue.replace(/oklab\(0% 0 0\/(\.\d+)\)/g, (match, alpha) => {
										const alphaValue = parseFloat(alpha);
										return `rgba(0, 0, 0, ${alphaValue})`;
									});

									// Convert var(--tw-shadow-color,xxx) patterns
									shadowValue = shadowValue.replace(/var\(--tw-shadow-color,([^)]+)\)/g, '$1');

									// Convert hex colors with alpha to rgba - dynamically parse hex values
									shadowValue = shadowValue.replace(/#([0-9a-fA-F]{6})([0-9a-fA-F]{2})/g, (match, rgb, alpha) => {
										const r = parseInt(rgb.substr(0, 2), 16);
										const g = parseInt(rgb.substr(2, 2), 16);
										const b = parseInt(rgb.substr(4, 2), 16);
										const a = parseInt(alpha, 16) / 255;
										return `rgba(${r}, ${g}, ${b}, ${a.toFixed(3)})`;
									});

									// Set the box-shadow directly to the converted value
									decl.value = shadowValue;
									shadowsProcessed++;

									// Debug logging in development
									if (process.env.NODE_ENV !== 'production') {
										console.log(`🔧 PostCSS: Fixed shadow ${rule.selector} -> ${shadowValue}`);
									}
								});

								// Remove the Tailwind variable declarations as they're no longer needed
								rule.walkDecls((varDecl) => {
									if (varDecl.prop.startsWith('--tw-shadow') || varDecl.prop === '--tw-inset-shadow' || varDecl.prop === '--tw-ring-shadow') {
										varDecl.remove();
									}
								});
							}
						}

						// Also handle --tw-shadow-color declarations directly
						if (decl.prop === '--tw-shadow-color') {
							// Convert oklab and color-mix patterns in shadow colors
							let colorValue = decl.value;

							// Convert NEW oklab(from rgb()) patterns in color values
							colorValue = colorValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\s+l\s+a\s+b\s*\/\s*(\d+)%\)\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
								const alpha = (parseFloat(percentAlpha) / 100);
								return `rgba(${r}, ${g}, ${b}, ${alpha})`;
							});

							colorValue = colorValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, baseAlpha, percentAlpha) => {
								const alpha = (parseFloat(percentAlpha) / 100);
								return `rgba(${r}, ${g}, ${b}, ${alpha})`;
							});

							colorValue = colorValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\s*\/\s*([\d.]+)\)\s+l\s+a\s+b\)/g, (match, r, g, b, alpha) => {
								return `rgba(${r}, ${g}, ${b}, ${alpha})`;
							});

							colorValue = colorValue.replace(/oklab\(from\s+rgb\((\d+)\s+(\d+)\s+(\d+)\)\s+l\s+a\s+b\s*\/\s*(\d+)%\)/g, (match, r, g, b, percentAlpha) => {
								const alpha = (parseFloat(percentAlpha) / 100);
								return `rgba(${r}, ${g}, ${b}, ${alpha})`;
							});

							// Convert hex with alpha
							colorValue = colorValue.replace(/#([0-9a-fA-F]{6})([0-9a-fA-F]{2})/g, (match, rgb, alpha) => {
								const r = parseInt(rgb.substr(0, 2), 16);
								const g = parseInt(rgb.substr(2, 2), 16);
								const b = parseInt(rgb.substr(4, 2), 16);
								const a = parseInt(alpha, 16) / 255;
								return `rgba(${r}, ${g}, ${b}, ${a.toFixed(3)})`;
							});

							// Convert color-mix patterns
							colorValue = colorValue.replace(/color-mix\(in oklab,([^)]+)\)/g, (match, content) => {
								// Parse percentage and convert to rgba
								const percentMatch = content.match(/(\d+)%/);
								if (percentMatch) {
									const percent = parseInt(percentMatch[1]) / 100;
									return `rgba(0, 0, 0, ${percent})`;
								}
								return match;
							});

							decl.value = colorValue;
						}
					});
				}
			},
			OnceExit(root, { Rule, Declaration }) {
				if (properties.length > 0) {
					const root_rule = new Rule({ selector: ':root, :host' });

					for (const prop of properties) {
						root_rule.append(
							new Declaration({
								prop: prop.name,
								value: prop.value,
							}),
						);
					}

					root.prepend(root_rule);
				}

				// Debug logging
				if (process.env.NODE_ENV !== 'production' && shadowsProcessed > 0) {
					console.log(`✅ PostCSS: Processed ${shadowsProcessed} shadow utilities for Shadow DOM`);
				}
			},
		};
	},
});

property_to_custom_prop.postcss = true;

module.exports = {
	plugins: [
		require('@tailwindcss/postcss'),
		property_to_custom_prop(),
		require('autoprefixer'),
	],
};

edited to add support for watch (watch uses more exotic from rgb syntax)