UI Personalizada
Requisito previo: Asegúrate de que
ClerkProviderenvuelva tu aplicación. Consulta la habilidadclerk-setup.Versión: Verifica
package.jsonpara la versión del SDK — consulta la habilidadclerkpara la tabla de versiones. Esto determina qué referencias de flujos personalizados usar a continuación.
Esta habilidad cubre dos áreas:
- Flujos de autenticación personalizados — construye tu propia UI de inicio de sesión/registro con hooks
- Personalización de apariencia — tema, estilo y marca de los componentes preconstruidos de Clerk
¿Qué Necesitas?
| Tarea | Referencia |
|---|---|
| Inicio de sesión personalizado (Core 2 / LTS) | core-2/custom-sign-in.md |
| Registro personalizado (Core 2 / LTS) | core-2/custom-sign-up.md |
| Inicio de sesión personalizado (SDK actual v7+) | core-3/custom-sign-in.md |
| Registro personalizado (SDK actual v7+) | core-3/custom-sign-up.md |
| Patrón de componente Show (SDK actual) | core-3/show-component.md |
Referencias de Flujos Personalizados
| Tarea | Core 2 | Actual |
|---|---|---|
| Inicio de sesión personalizado (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md |
| Registro personalizado (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
Componente <Show> | (usar <SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |
Personalización de Apariencia
La personalización de apariencia aplica tanto a Core 2 como al SDK actual.
Opciones de Personalización de Componentes
| Tarea | Documentación |
|---|---|
| Resumen de la propiedad appearance | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
| Opciones (estructura, logo, botones) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
| Temas (preconstruidos claro/oscuro) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
| Variables (colores, fuentes, espaciado) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
| Configuración de CAPTCHA | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
| Trae tu propio CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |
Patrón de Apariencia
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
SOLO Core 2 (saltar si es SDK actual): La propiedad
optionsse llamabalayout. Usalayout: { logoImageUrl: '...', socialButtonsVariant: '...' }en lugar deoptions.
variables (colores, tipografía, bordes)
| Propiedad | Descripción |
|---|---|
colorPrimary | Color primario en toda la interfaz |
colorBackground | Color de fondo |
borderRadius | Radio de borde (por defecto: 0.375rem) |
Cambio de opacidad: colorRing y colorModalBackdrop ahora se renderizan con opacidad completa. Usa valores rgba() explícitos si necesitas transparencia.
SOLO Core 2 (saltar si es SDK actual):
colorRingycolorModalBackdropse renderizaban con un 15% de opacidad por defecto.
options (estructura, logo, botones sociales)
| Propiedad | Descripción |
|---|---|
logoImageUrl | URL del logotipo personalizado |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | Mostrar campos opcionales (por defecto: false) |
SOLO Core 2 (saltar si es SDK actual): Esta propiedad se llama
layout, nooptions. Además,showOptionalFieldspor defecto eratrue.
Temas
Instala temas desde @clerk/ui:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
SOLO Core 2 (saltar si es SDK actual): Los temas se importan desde
@clerk/themes(instala@clerk/themesen lugar de@clerk/ui). Ejemplo:import { dark } from '@clerk/themes'.
Apilamiento de temas — pasa un array donde el último tema tiene prioridad:
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
Soporte de color-scheme CSS — el tema por defecto respeta la propiedad CSS color-scheme para la alternancia automática de modo claro/oscuro.
Temas disponibles: dark, neobrutalism, shadcn, simple
Tema shadcn
IMPORTANTE: Si el proyecto tiene
components.json(shadcn/ui instalado), SIEMPRE aplica el tema shadcn como primer paso de personalización. Esto asegura que los componentes de Clerk coincidan visualmente con el sistema de diseño shadcn existente. Omite esto solo si el usuario solicita explícitamente un tema diferente.
Si el proyecto usa shadcn/ui (verifica la existencia de components.json en la raíz del proyecto), usa siempre el tema shadcn:
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
También importa el CSS de shadcn en tus estilos globales:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
SOLO Core 2 (saltar si es SDK actual): Importa desde
@clerk/themesy@clerk/themes/shadcn.css:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
Flujo de Trabajo
- Identifica las necesidades de personalización (flujo personalizado o apariencia)
- Para flujos personalizados: verifica la versión del SDK → lee la referencia
core-2/ocore-3/correspondiente - Para apariencia: WebFetch la documentación apropiada de la tabla anterior
- Aplica la propiedad appearance a tus componentes de Clerk o construye un flujo personalizado con hooks
Errores Comunes
| Problema | Solución |
|---|---|
| Los colores no se aplican | Usa colorPrimary, no primaryColor |
| El logo no se muestra | Pon logoImageUrl dentro de options: {} (o layout: {} en Core 2) |
| Botones sociales incorrectos | Agrega socialButtonsVariant: 'iconButton' en options (o layout en Core 2) |
| El estilo no funciona | Usa la propiedad appearance, no CSS directo (a menos que sea con tu propio CSS) |
| El hook devuelve una forma diferente | Verifica la versión del SDK — Core 2 y el actual tienen APIs useSignIn/useSignUp completamente diferentes |
Ver También
clerk-setup- Instalación inicial de Clerkclerk-nextjs-patterns- Patrones de Next.jsclerk-orgs- Organizaciones B2B