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

# Passwords

> Learn about password management features in Nile Auth

## Features

* Password reset
* Password policies
* Password hashing and security

## Overview

With an SMTP provider configured on your database, users with emails can reset their passwords with a two step process. First, the users requests a link to be sent to their email address. The auth service creates a token (saved to the `auth.verification_tokens` table in your database), and sends it in an email. The token is valid for 4 hours by default.

## Installation

```sh theme={null}
npm install @niledatabase/react @niledatabase/client
```

## Usage

`/user/reset-password`

```tsx theme={null}
import { PasswordResetRequestForm } from './path/to/ResetForm';

const MyComponent = () => {
  return <PasswordResetRequestForm callbackUrl="/change-password" />;
};
```

<iframe src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=reset-password-form--request-reset-password" width="100%" height="250px" className="rounded-md" />

Once the user clicks on the link, they will be redirected to your app and will be able to securely reset their password.

`/user/change-password`

```tsx theme={null}
<PasswordResetForm
  defaultValues={{ email: 'user@example.com' }}
  onSuccess={() => console.log('Password updated successfully')}
  onError={(error) => console.error('Update failed', error)}
/>
```

<iframe src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=reset-password-form--reset-password" width="100%" height="480px" className="rounded-md" />

## API

### `PasswordResetRequestForm` Props

| Name            | Type                                                    | Default                                            | Description                                               |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `client`        | `QueryClient` *(optional)*                              | `undefined`                                        | React Query client instance.                              |
| `callbackUrl`   | `string` *(optional)*                                   | `undefined`                                        | The URL to redirect to after a successful password reset. |
| `defaultValues` | `object` *(optional)*                                   | `{ email: '', password: '', confirmPassword: '' }` | Default form values.                                      |
| `beforeMutate`  | `(data: AllowedAny) => AllowedAny` *(optional)*         | `undefined`                                        | Function executed before mutation to modify request data. |
| `onSuccess`     | `(res: Response) => void` *(optional)*                  | `undefined`                                        | Callback triggered on successful password reset.          |
| `onError`       | `(error: Error, data: AllowedAny) => void` *(optional)* | `undefined`                                        | Callback triggered if the reset process fails.            |

### `PasswordResetForm` Props

| Name            | Type                                                    | Default                                            | Description                                               |
| --------------- | ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `client`        | `QueryClient` *(optional)*                              | `undefined`                                        | React Query client instance.                              |
| `callbackUrl`   | `string` *(optional)*                                   | `undefined`                                        | The URL to redirect to after a successful password reset. |
| `defaultValues` | `object` *(optional)*                                   | `{ email: '', password: '', confirmPassword: '' }` | Default form values.                                      |
| `beforeMutate`  | `(data: AllowedAny) => AllowedAny` *(optional)*         | `undefined`                                        | Function executed before mutation to modify request data. |
| `onSuccess`     | `(res: Response) => void` *(optional)*                  | `undefined`                                        | Callback triggered on successful password reset.          |
| `onError`       | `(error: Error, data: AllowedAny) => void` *(optional)* | `undefined`                                        | Callback triggered if the reset process fails.            |

## Internal Functionality

* Uses `useForm` from React Hook Form to handle form state.
* Calls `useResetPassword` with the provided email and password upon form submission.
* Implements password confirmation validation to ensure the user inputs matching passwords.
* Supports lifecycle hooks (`beforeMutate`, `onSuccess`, `onError`) for request customization.
* Disables the submit button if passwords do not match or required fields are missing.

## Related Topics

* [Email Templates](/auth/email/templates)
* [Email Verification](/auth/email/verification)