IU Personalizada
Pré-requisito: Certifique-se de que
ClerkProviderenvolve seu aplicativo. Veja o skillclerk-setup.Versão: Verifique o arquivo
package.jsonpara a versão do SDK — veja o skillclerkpara a tabela de versões. Isso determina quais referências de fluxo personalizado usar abaixo.
Este skill cobre duas áreas:
- Fluxos de autenticação personalizados — crie sua própria IU de login/cadastro com hooks
- Personalização de aparência — tema, estilo e marca dos componentes prontos do Clerk
Do Que Você Precisa?
| Tarefa | Referência |
|---|---|
| Login personalizado (Core 2 / LTS) | core-2/custom-sign-in.md |
| Cadastro personalizado (Core 2 / LTS) | core-2/custom-sign-up.md |
| Login personalizado (SDK Atual v7+) | core-3/custom-sign-in.md |
| Cadastro personalizado (SDK Atual v7+) | core-3/custom-sign-up.md |
| Padrão de componente Show (SDK Atual) | core-3/show-component.md |
Referências de Fluxo Personalizado
| Tarefa | Core 2 | Atual |
|---|---|---|
| Login personalizado (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md |
| Cadastro personalizado (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
Componente <Show> | (use <SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |
Personalização de Aparência
A personalização de aparência se aplica tanto ao Core 2 quanto ao SDK atual.
Opções de Personalização de Componentes
| Tarefa | Documentação |
|---|---|
| Visão geral da prop appearance | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview |
| Opções (estrutura, logotipo, botões) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout |
| Temas (pré-construídos claro/escuro) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes |
| Variáveis (cores, fontes, espaçamento) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables |
| Configuração de CAPTCHA | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha |
| Traga seu próprio CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |
Padrão de Aparência
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
APENAS Core 2 (pule se for SDK atual): A propriedade
optionsera nomeadalayout. Uselayout: { logoImageUrl: '...', socialButtonsVariant: '...' }em vez deoptions.
variables (cores, tipografia, bordas)
| Propriedade | Descrição |
|---|---|
colorPrimary | Cor principal em todo o componente |
colorBackground | Cor de fundo |
borderRadius | Raio da borda (padrão: 0.375rem) |
Mudança de opacidade: colorRing e colorModalBackdrop agora renderizam com opacidade total. Use valores rgba() explícitos se precisar de transparência.
APENAS Core 2 (pule se for SDK atual):
colorRingecolorModalBackdroprenderizavam com 15% de opacidade por padrão.
options (estrutura, logotipo, botões sociais)
| Propriedade | Descrição |
|---|---|
logoImageUrl | URL para logotipo personalizado |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | Mostrar campos opcionais (padrão: false) |
APENAS Core 2 (pule se for SDK atual): Esta propriedade se chama
layout, nãooptions. Além disso,showOptionalFieldsera padronizado comotrue.
Temas
Instale temas a partir de @clerk/ui:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
APENAS Core 2 (pule se for SDK atual): Os temas são importados de
@clerk/themes(instale@clerk/themesem vez de@clerk/ui). Exemplo:import { dark } from '@clerk/themes'.
Empilhamento de temas — passe um array onde o último tema tem precedência:
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
Suporte a CSS color-scheme — o tema padrão respeita a propriedade CSS color-scheme para alternância automática entre modo claro/escuro.
Temas disponíveis: dark, neobrutalism, shadcn, simple
Tema shadcn
IMPORTANTE: Se o projeto tiver
components.json(shadcn/ui instalado), SEMPRE aplique o tema shadcn como PRIMEIRA etapa de personalização. Isso garante que os componentes do Clerk correspondam visualmente ao sistema de design shadcn existente. Pule isso apenas se o usuário solicitar explicitamente um tema diferente.
Se o projeto usa shadcn/ui (verifique se existe components.json na raiz do projeto), sempre use o tema shadcn:
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
Importe também o CSS shadcn em seus estilos globais:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
APENAS Core 2 (pule se for SDK atual): Importe de
@clerk/themese@clerk/themes/shadcn.css:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
Fluxo de Trabalho
- Identifique as necessidades de personalização (fluxo personalizado ou aparência)
- Para fluxos personalizados: verifique a versão do SDK → leia a referência apropriada
core-2/oucore-3/ - Para aparência: faça WebFetch da documentação apropriada da tabela acima
- Aplique a prop appearance aos seus componentes Clerk ou construa um fluxo personalizado com hooks
Problemas Comuns
| Problema | Solução |
|---|---|
| Cores não estão sendo aplicadas | Use colorPrimary, não primaryColor |
| Logotipo não aparece | Coloque logoImageUrl dentro de options: {} (ou layout: {} no Core 2) |
| Botões sociais errados | Adicione socialButtonsVariant: 'iconButton' em options (ou layout no Core 2) |
| Estilização não funciona | Use a prop appearance, não CSS direto (a menos que use bring-your-own-css) |
| Hook retorna formato diferente | Verifique a versão do SDK — Core 2 e atual têm APIs useSignIn/useSignUp completamente diferentes |
Veja Também
clerk-setup— Instalação inicial do Clerkclerk-nextjs-patterns— Padrões Next.jsclerk-orgs— Organizações B2B