> ## 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.

# Sign In

> Learn how to use the Nile Auth Sign In component

export const component_0 = "<SignIn />"

Users can sign up and be entered into the database via email + password. A JWT is used (which has a default expiry in 30 days). For Single Sign On, sessions are kept in the database in the `auth.session` table.
`@tanstack/react-query` and `react-hook-form` are used to do much of the heavy lifting in the component. The component is styled via tailwind.

## Installation

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

## Email + Password Sign In

Uses simple `<Email />` and `<Password />` fields, along with the `useSignIn()` hook to sign a user in, if they exist. In most cases, you want to supply a `callbackUrl`, which is where the user will be redirected upon successful sign in. Error handling works the same as it does in `<SignUpForm />`

<Tabs>
  <Tab title="Preview">
    <iframe src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=sign-in-form--sign-in-form" width="100%" height="400px" className="rounded-xl" />
  </Tab>

  <Tab title="Component">
    ```jsx theme={null}
    import { SignInForm } from "@niledatabase/react";

    export default function SignUpPage() {
      return <SignInForm callbackUrl="/dashboard" />
    }
    ```
  </Tab>
</Tabs>

## Email Only Sign In

With an SMTP provider configured on your database, users can supply their emails and be sent a link for sign in. The users enters their email, which causes the auth service to create a token (saved to the auth.verification\_tokens table in your database), and send it in an email. The token is valid for 4 hours by default.

Once the user clicks the link, they will exchange their token for a session and be redirected to whichever page was provided in the `callbackUrl`

<Tabs>
  <Tab title="Preview">
    <iframe src="https://storybook.thenile.dev/iframe.html?args=&globals=&id=social-email--sign-in-with-email" width="100%" height="230px" className="rounded-xl" />
  </Tab>

  <Tab title="Component">
    ```jsx theme={null}
    import { EmailSignIn } from "@niledatabase/react";

    export default function SignUpPage() {
      return <EmailSignIn callbackUrl="/dashboard" />
    }
    ```
  </Tab>
</Tabs>

## Hooks

### useSignIn

The `useSignIn` hook provides a way to authenticate users using credential-based sign-in within a React application. It utilizes React Query's `useMutation` to handle authentication requests and supports optional lifecycle callbacks for customization.

#### Installation

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

#### Usage

```tsx theme={null}
import { useSignIn } from '@niledatabase/react';

const SignInComponent = () => {
  const signIn = useSignIn({
    beforeMutate: (data) => ({ ...data, extraParam: 'value' }),
    onSuccess: () => console.log('Login successful'),
    onError: (error) => console.error('Login failed', error),
    callbackUrl: '/dashboard',
  });

  const handleLogin = () => {
    signIn({ email: 'user@example.com', password: 'securepassword' });
  };

  return <button onClick={handleLogin}>Sign In</button>;
};
```

#### API

##### `useSignIn(params?: Props): (data: LoginInfo) => void`

##### Parameters

| Name     | Type                 | Description           |
| -------- | -------------------- | --------------------- |
| `params` | `Props` *(optional)* | Configuration options |

##### Returns

A function that accepts `LoginInfo` containing user credentials to initiate the sign-in process.

#### Props

| Name           | Type                                             | Description                                                                                   |
| -------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `callbackUrl`  | `string` *(recommended)*                         | The URL to redirect to upon successful login.                                                 |
| `beforeMutate` | `(data: any) => any` *(optional)*                | Optional function executed before the mutation occurs, allowing modification of request data. |
| `onSuccess`    | `(data: LoginSuccess) => void` *(optional)*      | Callback function triggered on a successful login.                                            |
| `onError`      | `(error: Error, data: any) => void` *(optional)* | Callback function triggered if the login fails.                                               |
| `client`       | `QueryClient` *(optional)*                       | React Query client instance.                                                                  |

##### LoginInfo Type

```ts theme={null}
export type LoginInfo = {
  email: string;
  password: string;
};
```

##### Example with Error Handling

```tsx theme={null}
const signIn = useSignIn({
  onSuccess={async (res) => {
    if (res.ok) {
      // something good happened
    } else {
      const error = await res.text();
      console.error(error);
    }
  }}
  onError={(e)=> {
    console.error('Catastrophic failure 😭', e)
  }}
});

signIn({ email: "user@example.com", password: "wrongpassword" });
```

* Ensure that authentication providers are properly configured in your Next.js app.
* Use `beforeMutate` to modify request payloads before submission.
* The `callbackUrl` parameter determines the redirection URL post-login.

## Theming

The <code>{component_0}</code> component is styled using tailwind. It can be customized using the `className` and `buttonText` props,
or using Tailwind CSS theme variables. You can find more details and full examples in the [customization doc](/auth/components/customization).

In addition, the hooks documented for each component can be used if you'd like to use Nile Auth with your own components.
If needed, you can peek at the [source code of the component](https://github.com/niledatabase/nile-js/tree/main/packages/react/src) and use it as a template to create your own component for maximum customization.

## Related Components

* [Single Sign On](/auth/singlesignon)
* [Sign Out](/auth/components/signout)
* [User Profile](/auth/components/user)