UI Library Introduction
Relevant source files
The following files were used as context for generating this wiki page:The ui library is a collection of dynamic and reusable UI components designed for the Better Auth ecosystem. It provides pre-built, shadcn-based components for common authentication flows, enabling developers to quickly implement sign-up, sign-in, password recovery, and other auth-related user interfaces. The library is structured around a component registry, making it extensible and easy to manage.
The core purpose of this library is to offer a consistent and high-quality user interface for applications using Better Auth. It leverages modern frontend technologies like React, TypeScript, and Tailwind CSS to deliver a polished user experience out of the box.
Sources: packages/libraries/ui/README.md, packages/libraries/ui/package.json:4,14
Core Technologies and Dependencies
The UI library is built upon a modern stack of frontend tools and libraries. The key dependencies define its capabilities, from form handling and validation to styling and icons.
Sources: packages/libraries/ui/package.json
Key Dependencies Table
| Dependency | Version | Description |
|---|---|---|
better-auth | ^1.2.1 | The core peer dependency that this UI library is built for. |
@hookform/resolvers | ^4.1.3 | Provides a resolver to use Zod for validation with React Hook Form. |
react-hook-form | ^7.54.2 | Used for building performant and flexible forms in React. |
zod | ^3.24.2 | A TypeScript-first schema declaration and validation library, used for defining form validation rules. |
shadcn | ^2.4.0-canary.13 | The core UI component framework used for building the components. |
lucide-react | ^0.479.0 | Provides a set of simply beautiful and consistent icons. |
class-variance-authority | ^0.7.1 | A utility for creating variant-driven UI components. |
clsx | ^2.1.1 | A tiny utility for constructing className strings conditionally. |
tailwind-merge | ^3.0.2 | A utility to merge Tailwind CSS classes in JS without style conflicts. |
tailwindcss-animate | ^1.0.7 | A Tailwind CSS plugin for adding enter/exit animations. |
sonner | ^2.0.1 | An opinionated toast component for React, used for displaying success and error notifications. |
Sources: packages/libraries/ui/package.json:28-42, packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx:13
Component Registry
The UI library uses a JSON-based registry system to define and manage its components. The registry.json file acts as a manifest, listing all available components and their metadata. This approach allows for a decoupled and easily maintainable component system.
Sources: packages/libraries/ui/registry.json
Registry Item Structure
Each component in the registry is defined by an object with several key properties:
name: A unique identifier for the component (e.g.,sign-up).type: The type of registry item, typicallyregistry:componentorregistry:block.title: A human-readable title (e.g., "Sign Up").description: A brief explanation of the component's purpose.dependencies: External npm package dependencies.registryDependencies: Dependencies on other components within the same registry (e.g.,form,input).files: An array of file objects, specifying the path to the component's source code.
The diagram below illustrates the structure of a typical component entry in registry.json.
Available Components
The registry includes a variety of components for different authentication and user management tasks.
| Component Name | Title | Description | Registry Dependencies |
|---|---|---|---|
sign-up | Sign Up | A sign up component for Better Auth. | form, input, button |
sign-in | Sign In | A sign in component for Better Auth. | form, input, button |
forgot-password | Forgot Password | A forgot password component for Better Auth. | form, input, button |
reset-password | Reset Password | A reset password component for Better Auth. | form, input, button |
oauth | OAuth | A generic OAuth component for Better Auth. | - |
google-oauth | Google OAuth | A Google OAuth button component for Better Auth. | button |
discord-oauth | Discord OAuth | A Discord OAuth button component for Better Auth. | button |
Sources: packages/libraries/ui/registry.json
Component Architecture: The SignUp Example
To understand how components are built, we can analyze the SignUp component. It demonstrates the integration of form handling, validation, state management, and API communication.
Sources: packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx
Implementation Details
The SignUp component uses react-hook-form with a zodResolver to manage form state and validation. A Zod schema defines the expected shape and constraints of the form data.
// packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx:15-21
const formSchema = z.object({
name: z.string().min(2, {
message: "Name must be at least 2 characters",
}),
email: z.string().email(),
password: z.string().min(6, {
message: "Password must be at least 6 characters",
}),
});
Upon submission, the onSubmit function is called. It sets a loading state, calls the authClient.signUp.email method, and handles success and error cases by showing toast notifications and updating form errors.
User Sign-Up Flow
The following sequence diagram illustrates the interactions when a user submits the sign-up form.
This diagram shows the client-side flow from user interaction to API call and feedback.
Sources: packages/libraries/ui/registry/new-york/sign-up/sign-up.tsx:40-62
Contributing New Components
The project provides clear guidelines for contributing new components to the UI library. The process involves creating the component, registering it, and updating the build scripts.
Sources: packages/libraries/ui/contributions.md
Contribution Workflow
The following flowchart outlines the steps required to add a new component.
This structured process ensures that new components are correctly integrated into the library and the documentation site.
Sources: packages/libraries/ui/contributions.md