Directives

Les directives sont les règles at préfixées par @ que vous écrivez dans votre CSS d’entrée pour composer, étendre et ordonner la sortie de Tailwind. Cette page présente @apply, @utility, @variant, @custom-variant et @layer. @theme est présenté dans Thème ; @plugin dans Plugins ; et @source dans @source.

@apply

@apply insère les déclarations d’utilitaires existants dans votre propre sélecteur. Utilisez-le pour associer des styles d’utilitaires à une classe sémantique, y compris dans des sélecteurs imbriqués et des requêtes média.

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;
    }
');

Les variantes fonctionnent dans une liste @apply : @apply bg-blue-500 hover:bg-blue-600; développe l’état :hover et les préfixes adaptatifs tels que @apply px-4 md:px-6 lg:px-8; émettent les règles @media correspondantes. Le modificateur important est également pris en charge (@apply !flex;). Les sélecteurs imbriqués sont pris en charge ; une règle comme .card { h2 { @apply text-xl font-bold; } } applique donc les utilitaires au h2 imbriqué.

@apply est une instruction : @apply px-4 { … } suivie d’un corps provoque une erreur. Une règle @apply qui ne contient que des identifiants avec tirets (@apply --my-mixin;) est un mixin CSS du brouillon sur les mixins CSS, et non une liste d’utilitaires ; TailwindPHP ne la résout donc pas. Mélanger un mixin et des utilitaires dans le même @apply provoque une erreur (You cannot use @apply with both mixins and utilities…). Les règles de mixin sont actuellement supprimées de la sortie au lieu d’être transmises telles quelles (#12).

@utility

@utility enregistre un utilitaire personnalisé qui participe au moteur de Tailwind : il est trié dans la couche utilities et accepte les variantes comme les utilitaires intégrés. Un utilitaire statique utilise un corps fixe :

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

Comme il s’agit d’un véritable utilitaire, les variantes se composent automatiquement (hover:content-auto, md:content-auto). Le corps peut lui-même utiliser @apply et des sélecteurs imbriqués :

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

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

Un utilitaire fonctionnel utilise un suffixe -* dans son nom et lit la valeur correspondante avec --value() :

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

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

--value() résout la valeur du candidat à partir de chaque source à tour de rôle : un espace de noms du thème (--gutter-*), une valeur arbitraire avec un type de données ([length]) ou un type de valeur simple (integer, number, percentage, ratio). Toute déclaration dont le --value() ne peut pas être résolu est supprimée ; l’enchaînement des déclarations crée donc une chaîne de solutions de repli :

--modifier() résout la partie qui suit un / de la même façon : avec line-height: --modifier(integer); dans le corps, gutter-4/7 émet aussi line-height: 7. Les noms d’utilitaires suivent les règles TailwindCSS v4.3.3 : au plus un /, % uniquement à la fin après un chiffre, et des points uniquement entre les chiffres.

@variant

@variant applique une variante aux déclarations de votre propre CSS, sans définir d’utilitaire :

.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;
  }
}

Les variantes peuvent être empilées (@variant hover:focus), séparées par des virgules, imbriquées les unes dans les autres et peuvent désigner vos propres @custom-variants. Un @variant de premier niveau sans corps, ou avec @slot, est traité comme @custom-variant pour assurer la compatibilité ascendante.

@custom-variant

@custom-variant définit une nouvelle variante que vous pouvez ajouter en préfixe à n’importe quel utilitaire. La forme compacte nomme la variante et indique un sélecteur ou une règle at-rule entre parenthèses.

Une variante de liste de sélecteurs utilise & pour l’élément :

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

hocus:bg-blue-500 émet alors les règles :hover et :focus. Une forme avec attribut fonctionne de la même manière :

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

Une variante at-rule enveloppe les utilitaires correspondants dans cette règle at-rule :

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

Les variantes personnalisées s’empilent avec les variantes intégrées : sm:hocus:bg-blue-500 imbrique le sélecteur hocus dans la requête média sm. Pour les cas plus complexes, utilisez la forme bloc et indiquez avec @slot où injecter les déclarations de l’utilitaire :

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

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

@layer

@layer contrôle l’ordre de la cascade à l’aide des couches de cascade natives CSS. Une instruction @layer seule déclare l’ordre des couches ; les couches ultérieures l’emportent, quelle que soit la spécificité du sélecteur. L’ordre canonique de Tailwind est :

@layer theme, base, components, utilities;

C’est exactement ce que @import "tailwindcss" configure en interne. Vous pouvez déclarer votre propre ordre ou le répartir sur plusieurs instructions (@layer reset, base; puis @layer components, utilities;), et affecter des règles à une couche nommée avec un bloc :

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; }
    }
');

L’ajout de styles de base via @layer base les maintient sous components et utilities, de sorte qu’une classe utilitaire remplace toujours les valeurs par défaut de votre élément. Il en va de même pour @layer components { … }, qui sert aux classes de composants devant se trouver sous les utilitaires. Les couches anonymes et les modificateurs layer() sur @import sont abordés dans Imports.

Étapes suivantes

• Thème — @theme les jetons et les fonctions de thème.
• Imports — @import, les modules virtuels et les modificateurs layer().
• Plugins — la directive @plugin et le API du plugin.
• @source — contrôlez les fichiers et les classes analysés.