diff --git a/src/docs/styling-with-utility-classes.mdx b/src/docs/styling-with-utility-classes.mdx index d4466ab4d0..2a8b429a51 100644 --- a/src/docs/styling-with-utility-classes.mdx +++ b/src/docs/styling-with-utility-classes.mdx @@ -894,3 +894,102 @@ Here's what a `btn-primary` class might look like, using [theme variables](/docs Again though, for anything that's more complicated than just a single HTML element, we highly recommend using template partials so the styles and structure can be encapsulated in one place. + +## Managing style conflicts + +{/* All of the styles in Tailwind have fairly low specificity which can lead to style conflicts */} + +### Conflicting utility classes + +When you add two classes that target the same CSS property, the class that appears later in the stylesheet wins. So in this example, the element will receive `display: grid` even though `flex` comes last in the actual `class` attribute: + + + +```html + + +
+ +
+``` + +```css +/* [!code filename: CSS] */ +.flex { + display: flex; +} +.grid { + display: grid; +} +``` + +
+ +In general, you should just never add two conflicting classes to the same element — only ever add the one you actually want to take effect: + +```jsx +// [!code word:gridLayout\ \?\ \"grid\"\ \:\ \"flex\"] +function Example({ gridLayout }) { + return
{/* ... */}
; +} +``` + +Using component-based libraries like React or Vue, this often means exposing specific props for styling customizations instead of letting consumers add extra classes from outside of a component, since those styles will often conflict. + +### Using the important modifier + +When you really need to force a specific utility class to take effect and have no other means of managing the specificity, you can add `!` to the end of the class name to make all of the declarations `!important`: + + + +```html + + + +
+ +
+``` + +```css +/* [!code filename: Generated CSS] */ +/* [!code word:!important] */ +.bg-red-500\! { + background-color: var(--color-red-500) !important; +} +.bg-teal-500 { + background-color: var(--color-teal-500); +} +``` + +
+ +### Using the important flag + +If you're adding Tailwind to a project that has existing complex CSS with high specificity rules, you can use the `important` flag when importing Tailwind to mark _all_ utilities as `!important`: + + + +```css +/* [!code filename:app.css] */ +/* [!code word:important] */ +@import "tailwindcss" important; +``` + +```css +/* [!code filename:Compiled CSS] */ +/* [!code word:!important] */ +@layer utilities { + .flex { + display: flex !important; + } + .gap-4 { + gap: 1rem !important; + } + .underline { + text-decoration-line: underline !important; + } +} +``` + + diff --git a/src/docs/theme.mdx b/src/docs/theme.mdx index 5dae71b604..fa1d3cb095 100644 --- a/src/docs/theme.mdx +++ b/src/docs/theme.mdx @@ -1,3 +1,4 @@ +import { CodeExampleStack } from "@/components/code-example"; import { TipGood, TipBad, TipInfo } from "@/components/tips"; import { Iframe } from "@/components/iframe"; import { Example } from "@/components/example";