Personnaliser un composant

Ce que tu vas apprendre

• Les trois niveaux de personnalisation : class, ui et app.config.ts.
• Cibler une partie précise d'un composant grâce à ses slots.
• Changer les réglages par défaut de tous les boutons du site.

Trois niveaux, du plus local au plus global

Les deux premiers l'emportent sur la configuration globale. Commence par le plus simple.

La prop class

Un bouton arrondi, pour une seule page :

<UButton label="Lire" class="rounded-full" />

class accepte des classes Tailwind. Elle remplace le style de l'élément principal du composant, sa racine.

Pour un composant sans racine unique, ou pour viser une zone interne, passe à ui.

Les slots de style

Un composant est découpé en zones de style, aussi appelées slots (ne les confonds pas avec les slots de contenu). Pour UCard, ce sont root, header, body et footer, entre autres.

La documentation de chaque composant liste ses slots, dans la section du thème. Retiens que le nom sert de clé dans ui.

La prop ui

La prop ui reçoit un objet : une clé par zone, une chaîne de classes comme valeur.

<UCard :ui="{ header: 'bg-primary/10', footer: 'text-sm' }">
  <template #header>Tarte aux pommes</template>
  <p>Une recette simple.</p>
  <template #footer>Pour 6 personnes</template>
</UCard>

Ici, l'en-tête reçoit un fond teinté de la couleur primary et le pied de page un texte plus petit. Le corps de la carte ne change pas.

Personnaliser pour tout le site

Pour que tous les boutons changent, passe par app.config.ts, sous ui puis le nom du composant.

export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: 'font-bold'
      },
      defaultVariants: {
        color: 'neutral',
        variant: 'outline'
      }
    }
  }
})

• slots ajoute des classes à une zone de style : ici, tous les boutons passent en gras.
• defaultVariants change les réglages par défaut : sans précision, un bouton devient neutre et à contour.

Les variantes

Dans la configuration, variants décrit les classes de chaque valeur de color, variant ou size. compoundVariants cible une combinaison, par exemple un bouton error avec la variante outline.

button: {
  variants: {
    size: {
      md: { base: 'px-6' }
    }
  }
}

Ce système repose sur Tailwind Variants, une bibliothèque qui assemble des classes selon des variantes. Tu n'as pas à l'installer, Nuxt UI l'utilise déjà.

Quel niveau choisir ?

1. Un seul bouton à adapter : class.
2. Une zone interne d'un composant, une seule fois : ui.
3. Un style répété sur tout le site : app.config.ts.

Si tu copies la même prop ui dans cinq pages, c'est le signe qu'il faut la déplacer dans app.config.ts.

À retenir

• Trois niveaux : class (instance), ui (zones d'une instance), app.config.ts (tout le site).
• class agit sur la racine ; ui cible une zone par son nom de slot de style.
• Dans app.config.ts, on écrit ui.<composant> avec slots, variants, compoundVariants ou defaultVariants.
• Les props class et ui priment sur la configuration globale.
• Remonte un style répété vers app.config.ts.