Interface Utilisateur Personnalisée
Prérequis : Assurez-vous que
ClerkProviderenveloppe votre application. Voir la compétenceclerk-setup.Version : Vérifiez
package.jsonpour la version du SDK — voir la compétenceclerkpour le tableau des versions. Cela détermine les références de flux personnalisé à utiliser ci-dessous.
Cette compétence couvre deux domaines :
- Flux d'authentification personnalisés — construisez votre propre interface de connexion/inscription avec des hooks
- Personnalisation de l'apparence — thème, style et marque des composants préconstruits de Clerk
De quoi avez-vous besoin ?
| Tâche | Référence |
|---|---|
| Connexion personnalisée (Core 2 / LTS) | core-2/custom-sign-in.md |
| Inscription personnalisée (Core 2 / LTS) | core-2/custom-sign-up.md |
| Connexion personnalisée (SDK actuel v7+) | core-3/custom-sign-in.md |
| Inscription personnalisée (SDK actuel v7+) | core-3/custom-sign-up.md |
| Modèle d'affichage des composants (SDK actuel) | core-3/show-component.md |
Références des flux personnalisés
| Tâche | Core 2 | Actuel |
|---|---|---|
| Connexion personnalisée (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md |
| Inscription personnalisée (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
Composant <Show> | (utilisez <SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |
Personnalisation de l'apparence
La personnalisation de l'apparence s'applique à la fois à Core 2 et au SDK actuel.
Options de personnalisation des composants
| Tâche | Documentation |
|---|---|
| Aperçu de la propriété appearance | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
| Options (structure, logo, boutons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
| Thèmes (clair/sombre pré-construits) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
| Variables (couleurs, polices, espacement) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
| Configuration CAPTCHA | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
| Apportez votre propre CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |
Modèle d'apparence
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
Core 2 UNIQUEMENT (ignorez si SDK actuel) : La propriété
optionss'appelaitlayout. Utilisezlayout: { logoImageUrl: '...', socialButtonsVariant: '...' }à la place deoptions.
variables (couleurs, typographie, bordures)
| Propriété | Description |
|---|---|
colorPrimary | Couleur primaire générale |
colorBackground | Couleur d'arrière-plan |
borderRadius | Rayon de bordure (par défaut : 0.375rem) |
Changement d'opacité : colorRing et colorModalBackdrop s'affichent désormais en pleine opacité. Utilisez des valeurs rgba() explicites si vous avez besoin de transparence.
Core 2 UNIQUEMENT (ignorez si SDK actuel) :
colorRingetcolorModalBackdrops'affichaient avec une opacité de 15% par défaut.
options (structure, logo, boutons sociaux)
| Propriété | Description |
|---|---|
logoImageUrl | URL du logo personnalisé |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | Afficher les champs facultatifs (par défaut : false) |
Core 2 UNIQUEMENT (ignorez si SDK actuel) : Cette propriété s'appelle
layout, pasoptions. De plus,showOptionalFieldsétait par défauttrue.
Thèmes
Installez les thèmes depuis @clerk/ui :
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
Core 2 UNIQUEMENT (ignorez si SDK actuel) : Les thèmes sont importés depuis
@clerk/themes(installez@clerk/themesau lieu de@clerk/ui). Exemple :import { dark } from '@clerk/themes'.
Empilement de thèmes — passez un tableau où le dernier thème a la priorité :
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
Support de color-scheme CSS — le thème par défaut respecte la propriété CSS color-scheme pour le basculement automatique entre mode clair et sombre.
Thèmes disponibles : dark, neobrutalism, shadcn, simple
Thème shadcn
IMPORTANT : Si le projet contient
components.json(shadcn/ui installé), appliquez TOUJOURS le thème shadcn comme première étape de personnalisation. Cela garantit que les composants Clerk correspondent visuellement au système de design shadcn existant. Ignorez cette étape uniquement si l'utilisateur demande explicitement un autre thème.
Si le projet utilise shadcn/ui (vérifiez la présence de components.json à la racine du projet), utilisez toujours le thème shadcn :
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
Importez également le CSS shadcn dans vos styles globaux :
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
Core 2 UNIQUEMENT (ignorez si SDK actuel) : Importez depuis
@clerk/themeset@clerk/themes/shadcn.css:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
Workflow
- Identifiez les besoins de personnalisation (flux personnalisé ou apparence)
- Pour les flux personnalisés : vérifiez la version du SDK → lisez la référence appropriée
core-2/oucore-3/ - Pour l'apparence : récupérez la documentation appropriée via WebFetch depuis le tableau ci-dessus
- Appliquez la propriété appearance à vos composants Clerk ou construisez un flux personnalisé avec des hooks
Pièges courants
| Problème | Solution |
|---|---|
| Les couleurs ne s'appliquent pas | Utilisez colorPrimary et non primaryColor |
| Le logo ne s'affiche pas | Mettez logoImageUrl dans options: {} (ou layout: {} dans Core 2) |
| Boutons sociaux incorrects | Ajoutez socialButtonsVariant: 'iconButton' dans options (ou layout dans Core 2) |
| Le style ne fonctionne pas | Utilisez la propriété appearance, pas du CSS direct (sauf avec bring-your-own-css) |
| Le hook renvoie une forme différente | Vérifiez la version du SDK — Core 2 et l'actuel ont des API useSignIn/useSignUp complètement différentes |
Voir aussi
clerk-setup- Installation initiale de Clerkclerk-nextjs-patterns- Modèles Next.jsclerk-orgs- Organisations B2B