Customizing UI Components
Relevant source files
The following files were used as context for generating this wiki page:The ui library within Better Auth Kit provides a dynamic and customizable set of UI components for authentication flows. It is built upon shadcn/ui, leveraging Tailwind CSS for styling and offering a structured way to compose, extend, and create new components. This architecture allows developers to tailor the look and feel of authentication interfaces to match their application's design system.
Customization can be approached in several ways: by configuring the theme and styles, by composing existing components into new forms, or by contributing entirely new components to the library's registry. The system is designed to be modular, with clear definitions for components, their dependencies, and their files, making it maintainable and extensible.
UI Configuration (components.json)
The core configuration for the UI library is defined in components.json. This file, which follows the shadcn/ui schema, specifies the styling, file structure, and aliases for the project.
Sources: packages/libraries/ui/components.json
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "",
"css": "src/styles/globals.css",
"baseColor": "neutral",
"cssVariables": true,
"prefix": ""
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
},
"iconLibrary": "lucide"
}
Sources: packages/libraries/ui/components.json:1-21
Configuration Properties
| Property | Value | Description |
|---|---|---|
style | new-york | Defines the visual style of the components. |
rsc | false | Indicates that React Server Components are not used. |
tsx | true | Confirms that components are written in TSX. |
tailwind.cssVariables | true | Enables the use of CSS variables for theming. |
tailwind.baseColor | neutral | Sets the base color for the theme. |
aliases | {...} | Defines path aliases for imports, such as @/components and @/lib/utils. |
iconLibrary | lucide | Specifies lucide-react as the icon library. |
Sources: packages/libraries/ui/components.json:3-20, packages/libraries/ui/package.json:26
Component Registry (registry.json)
The registry.json file serves as a catalog for all UI components available in the better-auth-kit. It defines each component's metadata, dependencies, and associated files. This registry is essential for managing and building the components.
Sources: packages/libraries/ui/registry.json
The diagram below shows the structure of a component entry in the registry.
Registry Entry Example: sign-up
The sign-up component entry illustrates how a complex component is defined. It lists its external dependencies (better-auth, zod), its internal dependencies on other registry components (form, input, button), and all the source files that constitute the component.
{
"name": "sign-up",
"type": "registry:component",
"title": "Sign Up",
"description": "A sign up component for Better Auth.",
"dependencies": ["better-auth", "zod"],
"registryDependencies": ["form", "input", "button"],
"files": [
{
"path": "registry/new-york/sign-up/sign-up.tsx",
"type": "registry:block"
},
{
"path": "registry/new-york/name-field/name-field.tsx",
"type": "registry:component"
}
]
}
Sources: packages/libraries/ui/registry.json:8-29
Styling and Utilities
Styling is handled by Tailwind CSS, with animations powered by the tailwindcss-animate plugin. A key utility for applying conditional and dynamic classes is the cn function.
Sources: packages/libraries/ui/package.json:30, packages/libraries/ui/lib/utils.ts
The cn Utility
The cn function, located in lib/utils.ts, merges multiple class names using tailwind-merge and clsx. This is crucial for building customizable components where styles might be overridden or extended via props.
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
Sources: packages/libraries/ui/lib/utils.ts:1-5
Component Architecture: A Case Study (SignUp Component)
The SignUp component is a prime example of how components are structured and composed. It integrates form handling, validation, and API calls within a well-defined React component.
Sources: packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx
Composition
The SignUp component is not monolithic; it's built by composing several smaller, focused components. This promotes reusability and separation of concerns.
The diagram below illustrates the composition of the SignUp component.
Form Submission Flow
The component uses react-hook-form for state management and zod for schema validation. The onSubmit function handles the logic of calling the authClient, managing loading states, and displaying success or error notifications using sonner.
The following sequence diagram shows the user interaction flow when submitting the sign-up form.
Props
The SignUp component can be customized through its props.
| Prop | Type | Description |
|---|---|---|
onSuccess | (context: SuccessContext) => void | Callback function executed on successful sign-up. |
onError | (context: ErrorContext) => void | Callback function executed on sign-up failure. |
callbackURL | string | Optional URL to redirect to after a successful sign-up. |
className | string | Optional CSS classes to apply to the root container. |
Sources: packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx:43-48
Adding New UI Components
The project provides a clear, step-by-step guide for developers who wish to contribute new components. This process ensures that new components are correctly integrated into the registry and the build system.
Sources: packages/libraries/ui/contributions.md
The following flowchart outlines the contribution process.
Summary
Customizing UI components in Better Auth Kit is a flexible process rooted in the shadcn/ui methodology. Developers can leverage Tailwind CSS and CSS variables for theming, compose complex components from a rich set of primitives, and extend the library by adding new components through a well-documented contribution workflow. The entire system is cataloged in registry.json, providing a single source of truth for all UI elements.