[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)

[EyMaddis]

If you have runtime access to the CSS (I do in my case because I import tailwind via Vite's import css from 'main.css?inline').

You can just do something like this and use a simple Regex to extract all @property statements from the CSS file and then copy them to the document. There is of course a bit of Regex magic risk here (like bad performance or weird edge cases that only work in some cases. So be careful.
You can also just go to your css file and manually copy them from there. However, I do not know if the tailwind CLI will only include used variables (so the properties would change all the time), after a bit of experimentation I do not think this happens.

import mainCSS from 'main.css?inline' // only works for Vite // find all @property --foo {...} blocks const cssPropertyDefinitions = tailwindStyles.match(/(@property ([^}]*)\})/gms) ?? [] let propertyDefinitions = '' for (const definition of cssPropertyDefinitions) { propertyDefinitions += `${definition}\n` } // supports hot code replacements or rendering the same web component twice const tailwindStyleFixId = 'tailwind-shadow-root-style-fix' let styleElement = document.getElementById(tailwindStyleFixId) const didExist = !!styleElement if (!styleElement) { styleElement = document.createElement('style') styleElement.id = tailwindStyleFixId document.head.appendChild(styleElement) } styleElement.textContent = `  ${propertyDefinitions} `

[Peluko]

If you are using Vite and Lit, you can construct the style sheet via Lit's unsafeCSS() and process it as a Javascript object, extracting the properties and adding them to the document's style sheets without the worries of plain text processing. Here is what I use to construct the global stylesheet that will be shared to be used by the static styles property of my components:

import { unsafeCSS } from "lit"; import style from "../styles/global.css?inline"; const twCss = unsafeCSS(style); // Workaround for https://github.com/tailwindlabs/tailwindcss/issues/15005 if (twCss.styleSheet != undefined) { // Extract CSS property rules and add them to a separate stylesheet... const propertyStyleSheet = new CSSStyleSheet(); // CSSStyleSheet.deleteRule() modifies the stylesheet in place, so we need to // do some trickery to keep the indexes in sync const originalLength = twCss.styleSheet.cssRules.length; [...twCss.styleSheet.cssRules] .reverse() .forEach((rule, i) => { if (rule instanceof CSSPropertyRule) { propertyStyleSheet.insertRule(rule.cssText); twCss.styleSheet!.deleteRule(originalLength - 1 - i); } }); // ...then add the new stylesheet to the document document.adoptedStyleSheets.push(propertyStyleSheet); } export const globalStyles = twCss;