Directives

Directives zijn de met @ voorafgegane at-rules die je in je invoer-CSS schrijft om de uitvoer van Tailwind samen te stellen, uit te breiden en te ordenen. Deze pagina behandelt @apply, @utility, @variant, @custom-variant en @layer. @theme wordt behandeld in Thema; @plugin in Plugins; en @source in @source.

@apply

@apply voegt de declaraties van bestaande utilities in je eigen selector in. Gebruik deze om utilitystijlen aan een semantische klasse te koppelen, ook binnen geneste selectors en mediaquery's.

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

Varianten werken in een lijst met @apply — @apply bg-blue-500 hover:bg-blue-600; breidt de :hover-status uit, en responsieve prefixen zoals @apply px-4 md:px-6 lg:px-8; genereren de bijbehorende regels @media. Ook de belangrijke modifier wordt ondersteund (@apply !flex;). Geneste selectors worden ondersteund, zodat een regel zoals .card { h2 { @apply text-xl font-bold; } } utilities toepast op de geneste h2.

@apply is een instructie: @apply px-4 { … } met een body geeft een fout. Een @apply met alleen streepjesnamen (@apply --my-mixin;) is een CSS-mixin uit het conceptvoorstel voor mixins van CSS, geen utilitylijst. Daarom kan TailwindPHP deze niet oplossen; een mixin en utilities in dezelfde @apply plaatsen geeft een fout (You cannot use @apply with both mixins and utilities…). Mixinregels worden momenteel uit de uitvoer verwijderd in plaats van doorgegeven (#12).

@utility

@utility registreert een aangepaste utility die deelneemt aan de engine van Tailwind — deze wordt in de laag utilities geordend en accepteert varianten zoals elke ingebouwde utility. Een statische utility heeft een vaste body:

@utility content-auto {
    content-visibility: auto;
}

Omdat het een echte utility is, worden varianten automatisch gecombineerd (hover:content-auto, md:content-auto). De body mag zelf @apply en geneste selectors gebruiken:

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

Een functionele utility gebruikt een suffix -* in de naam en leest de overeenkomende waarde met --value():

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

--value() probeert de waarde van de kandidaat achtereenvolgens met elke bron te vinden: een themanaamruimte (--gutter-*), een willekeurige waarde met een gegevenstype ([length]) of een kale waardetype-aanduiding (integer, number, percentage, ratio). Een declaratie waarvan --value() niet wordt gevonden, vervalt; zo vormen meerdere declaraties samen een terugvalketen:

--modifier() verwerkt het deel na een / op dezelfde manier: met line-height: --modifier(integer); in de body geeft gutter-4/7 ook line-height: 7 uit. Namen van hulpprogramma's volgen de TailwindCSS-v4.3.3-regels: maximaal één /, % alleen aan het einde na een cijfer, en punten alleen tussen cijfers.

@variant

@variant past een variant toe op declaraties binnen je eigen CSS, zonder een hulpprogramma te definiëren:

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

Varianten kunnen worden gestapeld (@variant hover:focus), met komma's worden opgesomd, in elkaar worden genest en kunnen verwijzen naar je eigen @custom-variants. Een @variant op het hoogste niveau zonder body, of met @slot, wordt voor achterwaartse compatibiliteit behandeld als @custom-variant.

@custom-variant

@custom-variant definieert een nieuwe variant die je als prefix aan elk hulpprogramma kunt toevoegen. In de compacte vorm staat de naam van de variant met een selector of at-rule tussen haakjes.

Een variant met een selectorlijst gebruikt & voor het element:

@custom-variant hocus (&:hover, &:focus);

hocus:bg-blue-500 geeft vervolgens zowel de regels voor :hover als :focus uit. Een attribuutvorm werkt op dezelfde manier:

@custom-variant loading (&[data-loading="true"]);

Een at-rule-variant plaatst de overeenkomende hulpprogramma's binnen die at-rule:

@custom-variant tablet (@media (min-width: 600px));

Aangepaste varianten kunnen worden gestapeld met ingebouwde varianten — sm:hocus:bg-blue-500 nest de selector hocus binnen de mediaquery sm. Voor complexere gevallen gebruik je de blokvorm, waarbij @slot aangeeft waar de declaraties van het hulpprogramma worden ingevoegd:

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

@layer

@layer bepaalt de cascadevolgorde met native CSS-cascadelagen. Een losse @layer-instructie legt de volgorde van de lagen vast; latere lagen winnen, ongeacht de specificiteit van de selector. De canonieke volgorde van Tailwind is:

@layer theme, base, components, utilities;

Dit is precies wat @import "tailwindcss" intern instelt. Je kunt je eigen volgorde declareren of die over meerdere instructies verdelen (@layer reset, base; en daarna @layer components, utilities;), en regels aan een benoemde laag toewijzen met een blok:

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

Door basisstijlen toe te voegen via @layer base blijven ze onder components en utilities staan, zodat een hulpprogrammaklasse altijd de standaardstijlen van je element overschrijft. Hetzelfde geldt voor @layer components { … } voor componentklassen die onder hulpprogramma's moeten staan. Anonieme lagen en layer()-modifiers op @import worden behandeld bij Imports.

Volgende stappen

• Thema — @theme-tokens en de themafuncties.
• Imports — @import, virtuele modules en layer()-modifiers.
• Plugins — de @plugin-directive en de plugin-API.
• @source — bepaal welke bestanden en klassen worden gescand.