> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ub.bitbros.in/llms.txt
> Use this file to discover all available pages before exploring further.

# <UrAuth>

> A complete, drop-in authentication UI component.

The `<UrAuth>` component provides a beautiful, fully-functional authentication screen out of the box. It supports Email/Password login, Sign Up, Password Resets, and OAuth (Social Login).

## Usage

Simply drop the component into your login page. It will automatically detect if the user is logging in or signing up, and communicate with your urBackend project.

```tsx theme={null}
import { UrAuth } from '@urbackend/react';

export default function LoginPage() {
  return (
    <div style={{ display: 'flex', minHeight: '100vh', alignItems: 'center', justifyContent: 'center' }}>
      <UrAuth 
        providers={['google', 'github']}
        enableEmailPassword={true}
        theme="light" 
      />
    </div>
  );
}
```

## Props

| Prop                  | Type                                                                                          | Default                | Description                                                                 |
| --------------------- | --------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `theme`               | `'light' \| 'dark'`                                                                           | `'light'`              | Visual theme mode (`ThemeMode` internally).                                 |
| `providers`           | `('google' \| 'github')[] \| { google?: boolean; github?: boolean; emailPassword?: boolean }` | `['google', 'github']` | Auth methods to show. Supports legacy array form and v0.2.0 object form.    |
| `enableEmailPassword` | `boolean`                                                                                     | `true`                 | Top-level shorthand to enable/disable email/password auth.                  |
| `colors`              | `Partial<AuthColors>`                                                                         | `undefined`            | Overrides for auth widget theme colors.                                     |
| `branding`            | `AuthBranding`                                                                                | `undefined`            | Branding/white-label configuration (logo, app name, subtitle, brand color). |
| `labels`              | `Partial<AuthLabels>`                                                                         | `undefined`            | Text/copy overrides for tabs, titles, buttons, and footer prompts.          |
| `hideSignup`          | `boolean`                                                                                     | `false`                | Hides the sign up tab and sign up footer toggle when true.                  |
| `onSuccess`           | `() => void`                                                                                  | `undefined`            | Called after successful sign-in or sign-up flow.                            |

> All customization props are optional. If omitted, `<UrAuth>` falls back to the same default behavior/UI style as v0.1.x.

## `providers` and `enableEmailPassword`

`providers` now accepts either:

```ts theme={null}
('google' | 'github')[]
```

or:

```ts theme={null}
{
  google?: boolean;
  github?: boolean;
  emailPassword?: boolean;
}
```

### Example: Email/password only

```tsx theme={null}
<UrAuth
  providers={{ google: false, github: false, emailPassword: true }}
/>
```

### Example: Google only

```tsx theme={null}
<UrAuth
  providers={{ google: true, github: false, emailPassword: false }}
/>
```

### Example: Disable all methods

```tsx theme={null}
<UrAuth providers={{ google: false, github: false, emailPassword: false }} />
```

This renders the built-in `No authentication methods are enabled for this screen.` message.

### `enableEmailPassword` interaction

* `enableEmailPassword` is a shorthand global toggle.
* When `providers` is an object and includes `emailPassword`, that object value takes precedence.
* If `providers.emailPassword` is omitted, `enableEmailPassword` is used.

## `colors` theme customization

Use `colors` to override theme tokens:

```ts theme={null}
type AuthColors = {
  background: string;
  surface: string;
  text: string;
  textMuted: string;
  border: string;
  inputBackground: string;
  primary: string;
  primaryColor?: string; // alias for primary button color
  primaryText: string;
  footerBackground: string;
  dividerText: string;
  socialButtonBackground: string;
};
```

Set a custom brand color on the primary sign-in button:

```tsx theme={null}
<UrAuth colors={{ primaryColor: '#6366f1' }} />
```

If both `colors.primaryColor` and `branding.primaryColor` are provided, `branding.primaryColor` takes precedence.

## `branding` white-label options

```ts theme={null}
type AuthBranding = {
  brandName?: string;
  appName?: string;
  title?: string;
  subtitle?: string;
  logo?: React.ReactNode | string; // URL string or custom React node
  logoUrl?: string; // URL alias
  primaryColor?: string;
};
```

Example:

```tsx theme={null}
<UrAuth
  branding={{
    appName: 'Acme',
    logoUrl: 'https://acme.com/logo.png',
    subtitle: 'Secure access for your team',
  }}
/>
```

## `labels` text overrides (with aliases)

Supported label keys:

* Tabs: `loginTab` (`signInTab` alias), `signupTab` (`signUpTab` alias)
* Titles: `loginTitle` (`signInTitle` alias), `signupTitle` (`signUpTitle` alias), `forgotTitle`, `resetTitle`, `forgotSubtitle`, `resetSubtitle`
* Buttons: `loginButton` (`signInButton` alias), `signupButton` (`signUpButton` alias), `forgotButton`, `resetButton`, `googleButton`, `githubButton`
* Field labels/placeholders: `emailLabel`, `emailPlaceholder`, `passwordLabel`, `passwordPlaceholder`, `nameLabel`, `namePlaceholder`, `otpLabel`, `otpPlaceholder`
* Footer/misc: `forgotPasswordLink`, `socialDivider`, `footerSigninPrompt`, `footerSignupPrompt`, `footerForgotPrompt`, `noAuthMethods`

Example:

```tsx theme={null}
<UrAuth
  labels={{
    signInTitle: 'Welcome back to Acme',
    signInButton: 'Continue',
    footerSigninPrompt: 'Need an account?',
  }}
/>
```

## Full v0.2.0 customization example

```tsx theme={null}
import { UrAuth, GuestRoute } from '@urbackend/react';

export default function LoginPage() {
  return (
    <GuestRoute fallback={<div>Loading...</div>} onRedirect={() => (window.location.href = '/dashboard')}>
      <UrAuth
        providers={{
          github: true,
          google: true,
          emailPassword: true,
        }}
        enableEmailPassword={true}
        theme="light"
        colors={{
          primaryColor: '#4F46E5',
          socialButtonBackground: '#ffffff',
        }}
        branding={{
          appName: 'My Custom App',
          logoUrl: 'https://vite.dev/logo.svg',
          subtitle: 'Secure authentication',
          primaryColor: '#4F46E5',
        }}
        labels={{
          signInTitle: 'Welcome back to Custom App',
          signInButton: 'Proceed to App',
          signUpButton: 'Create your account',
        }}
        onSuccess={() => {
          // route after successful auth
          window.location.href = '/dashboard';
        }}
      />
    </GuestRoute>
  );
}
```

## Migration (v0.1.x → v0.2.0)

* `providers` now also accepts object form: `{ google?, github?, emailPassword? }`
* Existing array usage (`['google', 'github']`) still works
* No breaking API changes otherwise

## Behavior

1. **Email Login**: Prompts the user for email and password. If successful, updates the global `UrProvider` state automatically.
2. **Social Login**: Redirects the user to the provider (e.g. Google). Upon successful login, the user is redirected to the `Site URL` you configured in your urBackend Dashboard settings.
3. **Password Reset**: Allows users to request an OTP and reset their password inline.