Benutzerdefinierte Benutzeroberfläche
Voraussetzung: Stellen Sie sicher, dass
ClerkProviderIhre App umschließt. Siehe Skillclerk-setup.Version: Überprüfen Sie
package.jsonauf die SDK-Version – siehe Skillclerkfür die Versionstabelle. Diese bestimmt, welche Referenzen für benutzerdefinierte Abläufe unten verwendet werden.
Dieser Skill deckt zwei Bereiche ab:
- Benutzerdefinierte Authentifizierungsabläufe – erstellen Sie Ihre eigene Anmelde-/Registrierungsseite mit Hooks
- Anpassung des Erscheinungsbilds – Thema, Stil und Branding von Clerks vorgefertigten Komponenten
Was brauchen Sie?
| Aufgabe | Referenz |
|---|---|
| Benutzerdefinierte Anmeldung (Core 2 / LTS) | core-2/custom-sign-in.md |
| Benutzerdefinierte Registrierung (Core 2 / LTS) | core-2/custom-sign-up.md |
| Benutzerdefinierte Anmeldung (aktuelles SDK v7+) | core-3/custom-sign-in.md |
| Benutzerdefinierte Registrierung (aktuelles SDK v7+) | core-3/custom-sign-up.md |
| Komponentenmuster anzeigen (aktuelles SDK) | core-3/show-component.md |
Referenzen für benutzerdefinierte Abläufe
| Aufgabe | Core 2 | Aktuell |
|---|---|---|
| Benutzerdefinierte Anmeldung (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md |
| Benutzerdefinierte Registrierung (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
<Show>-Komponente | (verwenden Sie <SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |
Anpassung des Erscheinungsbilds
Die Anpassung des Erscheinungsbilds gilt sowohl für Core 2 als auch für das aktuelle SDK.
Optionen zur Komponentenanpassung
| Aufgabe | Dokumentation |
|---|---|
Übersicht über das appearance-Prop | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
| Optionen (Struktur, Logo, Schaltflächen) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
| Themes (vorgefertigt dunkel/hell) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
| Variablen (Farben, Schriften, Abstände) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
| CAPTCHA-Konfiguration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
| Eigenes CSS einbringen | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |
Muster für das Erscheinungsbild
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
NUR Core 2 (überspringen, wenn aktuelles SDK): Die
options-Eigenschaft hießlayout. Verwenden Sie stattdessenlayout: { logoImageUrl: '...', socialButtonsVariant: '...' }anstelle vonoptions.
variables (Farben, Typografie, Rahmen)
| Eigenschaft | Beschreibung |
|---|---|
colorPrimary | Primärfarbe im gesamten Erscheinungsbild |
colorBackground | Hintergrundfarbe |
borderRadius | Rahmenradius (Standard: 0.375rem) |
Änderung der Deckkraft: colorRing und colorModalBackdrop werden jetzt mit voller Deckkraft dargestellt. Verwenden Sie explizite rgba()-Werte, wenn Sie Transparenz benötigen.
NUR Core 2 (überspringen, wenn aktuelles SDK):
colorRingundcolorModalBackdropwurden standardmäßig mit 15% Deckkraft dargestellt.
options (Struktur, Logo, Social-Buttons)
| Eigenschaft | Beschreibung |
|---|---|
logoImageUrl | URL zum benutzerdefinierten Logo |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | Optionale Felder anzeigen (Standard: false) |
NUR Core 2 (überspringen, wenn aktuelles SDK): Diese Eigenschaft heißt
layout, nichtoptions. Außerdem warshowOptionalFieldsstandardmäßigtrue.
Themes
Installieren Sie Themes aus @clerk/ui:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
NUR Core 2 (überspringen, wenn aktuelles SDK): Themes werden aus
@clerk/themesimportiert (installieren Sie@clerk/themesanstelle von@clerk/ui). Beispiel:import { dark } from '@clerk/themes'.
Theme-Stacking – übergeben Sie ein Array, bei dem das letzte Theme Vorrang hat:
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
CSS color-scheme-Unterstützung – das Standard-Theme respektiert die CSS-Eigenschaft color-scheme für automatischen hellen/dunklen Modus.
Verfügbare Themes: dark, neobrutalism, shadcn, simple
shadcn-Theme
WICHTIG: Wenn das Projekt
components.jsonenthält (shadcn/ui installiert), wenden Sie IMMER das shadcn-Theme als ersten Anpassungsschritt an. Dadurch wird sichergestellt, dass Clerk-Komponenten visuell mit dem vorhandenen shadcn-Designsystem übereinstimmen. Überspringen Sie dies nur, wenn der Benutzer ausdrücklich ein anderes Theme anfordert.
Wenn das Projekt shadcn/ui verwendet (überprüfen Sie, ob components.json im Projektstamm vorhanden ist), verwenden Sie immer das shadcn-Theme:
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
Importieren Sie auch das shadcn-CSS in Ihre globalen Styles:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
NUR Core 2 (überspringen, wenn aktuelles SDK): Importieren Sie aus
@clerk/themesund@clerk/themes/shadcn.css:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
Arbeitsablauf
- Anpassungsbedarf identifizieren (benutzerdefinierter Ablauf oder Erscheinungsbild)
- Für benutzerdefinierte Abläufe: SDK-Version prüfen → entsprechende Referenz unter
core-2/odercore-3/lesen - Für das Erscheinungsbild: Die entsprechende Dokumentation aus der obigen Tabelle per WebFetch abrufen
- Das
appearance-Prop auf Ihre Clerk-Komponenten anwenden oder einen benutzerdefinierten Ablauf mit Hooks erstellen
Häufige Fallstricke
| Problem | Lösung |
|---|---|
| Farben werden nicht angewendet | Verwenden Sie colorPrimary, nicht primaryColor |
| Logo wird nicht angezeigt | Setzen Sie logoImageUrl innerhalb von options:{} (oder layout:{} in Core 2) |
| Social-Buttons falsch | Fügen Sie socialButtonsVariant: 'iconButton' in options (oder layout in Core 2) hinzu |
| Styling funktioniert nicht | Verwenden Sie das appearance-Prop, kein direktes CSS (es sei denn mit "bring your own CSS") |
| Hook gibt andere Struktur zurück | SDK-Version prüfen – Core 2 und aktuelles SDK haben völlig unterschiedliche useSignIn/useSignUp-APIs |
Siehe auch
clerk-setup- Ersteinrichtung von Clerkclerk-nextjs-patterns- Next.js-Musterclerk-orgs- B2B-Organisationen