사용자 정의 UI
전제 조건:
ClerkProvider가 앱을 감싸고 있는지 확인하세요.clerk-setup스킬을 참조하세요.버전:
package.json에서 SDK 버전을 확인하세요.clerk스킬의 버전 테이블을 참조하세요. 이에 따라 아래에서 사용할 사용자 정의 흐름 참조가 결정됩니다.
이 스킬은 두 가지 영역을 다룹니다:
- 사용자 정의 인증 흐름 — 훅을 사용하여 자체 로그인/회원가입 UI 구축
- 외형 커스터마이징 — Clerk의 사전 구축된 구성 요소 테마, 스타일, 브랜딩
무엇이 필요하신가요?
| 작업 | 참조 |
|---|---|
| 사용자 정의 로그인 (Core 2 / LTS) | core-2/custom-sign-in.md |
| 사용자 정의 회원가입 (Core 2 / LTS) | core-2/custom-sign-up.md |
| 사용자 정의 로그인 (현재 SDK v7+) | core-3/custom-sign-in.md |
| 사용자 정의 회원가입 (현재 SDK v7+) | core-3/custom-sign-up.md |
| 컴포넌트 표시 패턴 (현재 SDK) | core-3/show-component.md |
사용자 정의 흐름 참조
| 작업 | Core 2 | 현재 |
|---|---|---|
| 사용자 정의 로그인 (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md |
| 사용자 정의 회원가입 (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
<Show> 컴포넌트 | (<SignedIn>, <SignedOut>, <Protect> 사용) | core-3/show-component.md |
외형 커스터마이징
외형 커스터마이징은 Core 2와 현재 SDK 모두에 적용됩니다.
컴포넌트 커스터마이징 옵션
Appearance 패턴
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
Core 2 전용 (현재 SDK인 경우 건너뛰기):
options속성은layout으로 명명되었습니다.options대신layout: { logoImageUrl: '...', socialButtonsVariant: '...' }를 사용하세요.
variables (색상, 타이포그래피, 테두리)
| 속성 | 설명 |
|---|---|
colorPrimary | 전체 기본 색상 |
colorBackground | 배경 색상 |
borderRadius | 테두리 반경 (기본값: 0.375rem) |
불투명도 변경: colorRing 및 colorModalBackdrop은 이제 전체 불투명도로 렌더링됩니다. 투명도가 필요한 경우 명시적인 rgba() 값을 사용하세요.
Core 2 전용 (현재 SDK인 경우 건너뛰기):
colorRing및colorModalBackdrop은 기본적으로 15% 불투명도로 렌더링되었습니다.
options (구조, 로고, 소셜 버튼)
| 속성 | 설명 |
|---|---|
logoImageUrl | 사용자 정의 로고 URL |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | 선택적 필드 표시 (기본값: false) |
Core 2 전용 (현재 SDK인 경우 건너뛰기): 이 속성은
options가 아닌layout이라고 합니다. 또한showOptionalFields는 기본값이true였습니다.
테마
@clerk/ui에서 테마 설치:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
Core 2 전용 (현재 SDK인 경우 건너뛰기): 테마는
@clerk/themes에서 가져옵니다(@clerk/ui대신@clerk/themes설치). 예:import { dark } from '@clerk/themes'.
테마 스태킹 — 마지막 테마가 우선하는 배열을 전달합니다:
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
CSS color-scheme 지원 — 기본 테마는 CSS color-scheme 속성을 존중하여 자동 라이트/다크 모드 전환을 지원합니다.
사용 가능한 테마: dark, neobrutalism, shadcn, simple
shadcn 테마
중요: 프로젝트에
components.json(shadcn/ui 설치됨)이 있는 경우, 항상 첫 번째 커스터마이징 단계로 shadcn 테마를 적용하세요. 이렇게 하면 Clerk 구성 요소가 기존 shadcn 디자인 시스템과 시각적으로 일치합니다. 사용자가 명시적으로 다른 테마를 요청하는 경우에만 건너뛰세요.
프로젝트가 shadcn/ui를 사용하는 경우(프로젝트 루트에서 components.json 확인), 항상 shadcn 테마를 사용하세요:
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
또한 전역 스타일에 shadcn CSS를 가져옵니다:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
Core 2 전용 (현재 SDK인 경우 건너뛰기):
@clerk/themes및@clerk/themes/shadcn.css에서 가져옵니다:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
워크플로우
- 커스터마이징 요구 사항 식별 (사용자 정의 흐름 또는 외형)
- 사용자 정의 흐름의 경우: SDK 버전 확인 → 적절한
core-2/또는core-3/참조 읽기 - 외형의 경우: 위 표에서 적절한 문서 웹 가져오기
- Clerk 구성 요소에 appearance prop 적용 또는 훅으로 사용자 정의 흐름 구축
일반적인 문제
| 문제 | 해결 방법 |
|---|---|
| 색상이 적용되지 않음 | primaryColor가 아닌 colorPrimary 사용 |
| 로고가 표시되지 않음 | options: {}(또는 Core 2에서는 layout: {}) 안에 logoImageUrl 넣기 |
| 소셜 버튼이 잘못됨 | options(또는 Core 2에서는 layout)에 socialButtonsVariant: 'iconButton' 추가 |
| 스타일링이 작동하지 않음 | 직접 CSS 대신 appearance prop 사용 (bring-your-own-css 사용 시 제외) |
| 훅이 다른 형태 반환 | SDK 버전 확인 — Core 2와 현재는 useSignIn/useSignUp API가 완전히 다름 |
참고 항목
clerk-setup- 최초 Clerk 설치clerk-nextjs-patterns- Next.js 패턴clerk-orgs- B2B 조직