Authentication
Headless authentication components for user login, logout, password reset requests, and password reset functionality.
Purpose
This library provides headless authentication components for handling user login, logout, password reset requests, and password reset functionality. All components are designed to be completely customizable while providing the necessary authentication logic. The components expose all state and actions via context and render props, allowing complete control over styling and behavior.
Features
- Login form with email and password validation
- Logout functionality with optional redirect
- Password reset request flow
- Password reset with token validation
- Form validation: Built-in email and password validation
- Error handling: Comprehensive error handling with user-friendly messages
- Loading states: Loading indicators for all async operations
- Accessibility: Full ARIA support, keyboard navigation, and screen reader support
- Platform support: Works on both web and mobile platforms
Installation
- npm
- Yarn
npm install @haus-storefront-react/authentication
yarn add @haus-storefront-react/authentication
Note: This is not a public package. Contact the Haus Tech Team for access.
API Reference
Login
A headless component for managing user authentication. It provides functionality for login form handling. All state and actions are exposed via context and render props.
<Login.Root>
Context provider for login functionality.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
onLogin | (username: string) => Promise<void> | void | No | - | Callback when login succeeds |
onLoginError | (error: Error) => void | No | - | Callback when login fails |
children | ReactNode | ((props: LoginContextValue) => ReactNode) | No | - | Children or render prop function |
__scopeLogin | Scope | No | - | Internal scope for context isolation |
Context Value
| Property | Type | Description |
|---|---|---|
isLoading | boolean | Whether login is in progress |
loginError | Error | null | Login error if any |
loginSuccess | boolean | Whether login was successful |
login | (email: string, password: string) => Promise<void> | Function to perform login |
getFormProps | () => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getEmailInputProps | () => InputProps | Function that returns email input props with accessibility attributes |
getPasswordInputProps | () => InputProps | Function that returns password input props with accessibility attributes |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props with loading state |
<Login.Form>
Form component that handles submission. Handles form submission and exposes form props.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Form contents |
<Login.EmailInput>
Email input component for login form. Includes proper accessibility attributes, email validation, and password manager integration.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
| All standard input props | - | No | - | Additional input element props |
<Login.PasswordInput>
Password input component for login form. Includes proper accessibility attributes and password manager integration.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
| All standard input props | - | No | - | Additional input element props |
<Login.SubmitButton>
Submit button component for login form. Disabled while the login request is in progress. Includes proper accessibility attributes and loading state handling.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Button content |
| All standard button props | - | No | - | Additional button element props |
Logout
A headless component for managing user logout. It provides functionality for logging out users and handling the logout state. All state and actions are exposed via context and render props.
<Logout.Root>
Context provider for logout functionality.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
onLogout | () => Promise<void> | No | - | Callback when logout is triggered |
onLogoutError | (error: Error) => void | No | - | Callback when logout fails |
onLogoutRedirect | string | No | - | URL to redirect to after logout |
children | ReactNode | ((props: LogoutContextValue) => ReactNode) | No | - | Children or render prop function |
__scopeLogout | Scope | No | - | Internal scope for context isolation |
Context Value
| Property | Type | Description |
|---|---|---|
isLoading | boolean | Whether logout is in progress |
logoutError | Error | null | Logout error if any |
logoutSuccess | boolean | Whether logout was successful |
logout | () => Promise<void> | Function to perform logout |
getButtonProps | () => ButtonProps | Function that returns button props with loading state |
<Logout.Button>
Button component for logout. Disabled while the logout request is in progress. Includes proper accessibility attributes and loading state handling.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Button content |
| All standard button props | - | No | - | Additional button element props |
RequestReset
A headless component for requesting password reset emails. It provides functionality for submitting email addresses to receive password reset links. All state and actions are exposed via context and render props.
<RequestReset.Root>
Context provider for password reset request functionality.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
onPasswordReset | (email: string) => Promise<void> | void | No | - | Callback when reset email is sent |
onPasswordResetError | (error: Error) => void | No | - | Callback when reset request fails |
children | ReactNode | ((props: UseRequestResetReturn) => ReactNode) | No | - | Children or render prop function |
__scopeRequestReset | Scope | No | - | Internal scope for context isolation |
Context Value
| Property | Type | Description |
|---|---|---|
isLoading | boolean | Whether request is in progress |
requestResetError | Error | null | Request error if any |
requestResetSuccess | boolean | Whether request was successful |
requestPasswordReset | (email: string) => Promise<void> | Function to request password reset |
getFormProps | () => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getEmailInputProps | () => InputProps | Function that returns email input props with accessibility attributes |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props with loading state |
<RequestReset.Form>
Form component for requesting password reset. Handles form submission and exposes form props.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Form contents |
<RequestReset.EmailInput>
Email input component for password reset request form. Includes proper accessibility attributes and email validation.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
| All standard input props | - | No | - | Additional input element props |
<RequestReset.SubmitButton>
Submit button component for password reset request form. Disabled while the reset request is in progress. Includes proper accessibility attributes and loading state handling.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Button content |
| All standard button props | - | No | - | Additional button element props |
ResetPassword
A headless component for resetting passwords with a token. It provides functionality for submitting new passwords and confirming them. All state and actions are exposed via context and render props.
<ResetPassword.Root>
Context provider for password reset functionality.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
token | string | Yes | - | Reset token from email |
onReset | () => void | No | - | Callback when password is reset |
onResetError | (error: Error) => void | No | - | Callback when reset fails |
children | ReactNode | ((props: UseResetPasswordReturn) => ReactNode) | No | - | Children or render prop function |
__scopeResetPassword | Scope | No | - | Internal scope for context isolation |
Context Value
| Property | Type | Description |
|---|---|---|
isLoading | boolean | Whether reset is in progress |
resetPasswordError | Error | null | Reset error if any |
resetPasswordSuccess | boolean | Whether reset was successful |
resetPassword | (token: string, password: string) => Promise<void> | Function to reset password |
getFormProps | (token: string) => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getPasswordInputProps | () => InputProps | Function that returns password input props with accessibility attributes |
getPasswordConfirmationInputProps | () => InputProps | Function that returns password confirmation input props with accessibility attributes |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props with loading state |
<ResetPassword.Form>
Form component for resetting password. Handles form submission and exposes form props. Validates that passwords match before submission. Includes a hidden username field for accessibility and password manager compatibility.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
token | string | Yes | - | Reset token from email |
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Form contents |
<ResetPassword.PasswordInput>
Password input component for new password. Includes proper accessibility attributes and password manager integration.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
| All standard input props | - | No | - | Additional input element props |
<ResetPassword.PasswordConfirmationInput>
Password confirmation input component. Used to verify the new password is entered correctly. Includes proper accessibility attributes and password manager integration.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
| All standard input props | - | No | - | Additional input element props |
<ResetPassword.SubmitButton>
Submit button component for password reset form. Disabled while the reset request is in progress. Includes proper accessibility attributes and loading state handling.
Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
asChild | boolean | No | false | Whether to render as a slot for custom styling |
children | ReactNode | No | - | Button content |
| All standard button props | - | No | - | Additional button element props |
useLoginProps
Hook that provides login functionality and form/input prop getters. Used internally by <Login.Root> but can be used standalone for custom implementations.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options | UseLoginProps | Yes | Configuration object |
Options Object
interface UseLoginProps {
onLogin?: (username: string) => Promise<void> | void
onLoginError?: (error: Error) => void
}
Returns
| Return Value | Type | Description |
|---|---|---|
isLoading | boolean | Whether login is in progress |
loginError | Error | null | Login error if any |
loginSuccess | boolean | Whether login was successful |
login | (username: string, password: string) => Promise<void> | Function to perform login |
getFormProps | () => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getEmailInputProps | () => InputProps | Function that returns email input props |
getPasswordInputProps | () => InputProps | Function that returns password input props |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props |
useLogoutProps
Hook that provides logout functionality and button prop getters. Used internally by <Logout.Root> but can be used standalone for custom implementations.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options | UseLogoutProps | Yes | Configuration object |
Options Object
interface UseLogoutProps {
onLogout?: () => Promise<void>
onLogoutError?: (error: Error) => void
onLogoutRedirect?: string
}
Returns
| Return Value | Type | Description |
|---|---|---|
isLoading | boolean | Whether logout is in progress |
logoutError | Error | null | Logout error if any |
logoutSuccess | boolean | Whether logout was successful |
logout | () => Promise<void> | Function to perform logout |
getButtonProps | () => ButtonProps | Function that returns button props |
useRequestResetProps
Hook that provides password reset request functionality and form/input prop getters. Used internally by <RequestReset.Root> but can be used standalone for custom implementations.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options | UseRequestResetProps | Yes | Configuration object |
Options Object
interface UseRequestResetProps {
onPasswordReset?: (email: string) => Promise<void> | void
onPasswordResetError?: (error: Error) => void
}
Returns
| Return Value | Type | Description |
|---|---|---|
isLoading | boolean | Whether request is in progress |
requestResetError | Error | null | Request error if any |
requestResetSuccess | boolean | Whether request was successful |
requestPasswordReset | (email: string) => Promise<void> | Function to request password reset |
getFormProps | () => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getEmailInputProps | () => InputProps | Function that returns email input props |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props |
useResetPasswordProps
Hook that provides password reset functionality and form/input prop getters. Used internally by <ResetPassword.Root> but can be used standalone for custom implementations.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options | UseResetPasswordProps | Yes | Configuration object |
Options Object
interface UseResetPasswordProps {
onReset?: () => void
onResetError?: (error: Error) => void
}
Returns
| Return Value | Type | Description |
|---|---|---|
isLoading | boolean | Whether reset is in progress |
resetPasswordError | Error | null | Reset error if any |
resetPasswordSuccess | boolean | Whether reset was successful |
resetPassword | (token: string, password: string) => Promise<void> | Function to reset password |
getFormProps | (token: string) => { onSubmit: (e: React.FormEvent) => void } | Function that returns form submission props |
getPasswordInputProps | () => InputProps | Function that returns password input props |
getPasswordConfirmationInputProps | () => InputProps | Function that returns password confirmation input props |
getSubmitButtonProps | () => ButtonProps | Function that returns submit button props |
Basic Usage
Simple Login Form
- React
- React Native
import { Login } from '@haus-storefront-react/authentication'
function LoginForm() {
return (
<Login.Root>
<Login.Form>
<Login.EmailInput />
<Login.PasswordInput />
<Login.SubmitButton>Login</Login.SubmitButton>
</Login.Form>
</Login.Root>
)
}
import { Login } from '@haus-storefront-react/authentication'
function LoginForm() {
return (
<Login.Root>
<Login.Form>
<Login.EmailInput />
<Login.PasswordInput />
<Login.SubmitButton>Login</Login.SubmitButton>
</Login.Form>
</Login.Root>
)
}
Simple Logout Button
- React
- React Native
import { Logout } from '@haus-storefront-react/authentication'
function LogoutButton() {
return (
<Logout.Root>
<Logout.Button>Logout</Logout.Button>
</Logout.Root>
)
}
import { Logout } from '@haus-storefront-react/authentication'
function LogoutButton() {
return (
<Logout.Root>
<Logout.Button>Logout</Logout.Button>
</Logout.Root>
)
}
Password Reset Request
- React
- React Native
import { RequestReset } from '@haus-storefront-react/authentication'
function PasswordResetRequest() {
return (
<RequestReset.Root>
<RequestReset.Form>
<RequestReset.EmailInput />
<RequestReset.SubmitButton>Send Reset Email</RequestReset.SubmitButton>
</RequestReset.Form>
</RequestReset.Root>
)
}
import { RequestReset } from '@haus-storefront-react/authentication'
function PasswordResetRequest() {
return (
<RequestReset.Root>
<RequestReset.Form>
<RequestReset.EmailInput />
<RequestReset.SubmitButton>Send Reset Email</RequestReset.SubmitButton>
</RequestReset.Form>
</RequestReset.Root>
)
}
Password Reset
- React
- React Native
import { ResetPassword } from '@haus-storefront-react/authentication'
function PasswordReset({ token }: { token: string }) {
return (
<ResetPassword.Root token={token}>
<ResetPassword.Form token={token}>
<ResetPassword.PasswordInput />
<ResetPassword.PasswordConfirmationInput />
<ResetPassword.SubmitButton>Reset Password</ResetPassword.SubmitButton>
</ResetPassword.Form>
</ResetPassword.Root>
)
}
import { ResetPassword } from '@haus-storefront-react/authentication'
function PasswordReset({ token }: { token: string }) {
return (
<ResetPassword.Root token={token}>
<ResetPassword.Form token={token}>
<ResetPassword.PasswordInput />
<ResetPassword.PasswordConfirmationInput />
<ResetPassword.SubmitButton>Reset Password</ResetPassword.SubmitButton>
</ResetPassword.Form>
</ResetPassword.Root>
)
}
Advanced Usage
Custom Login with Render Props
- React
- React Native
import { Login } from '@haus-storefront-react/authentication'
function CustomLoginForm() {
return (
<Login.Root
onLogin={(username) => console.log('Logged in:', username)}
onLoginError={(error) => console.error('Login failed:', error)}
>
{({
isLoading,
loginError,
loginSuccess,
login,
getFormProps,
getEmailInputProps,
getPasswordInputProps,
getSubmitButtonProps,
}) => (
<form
{...getFormProps()}
className='custom-login-form'
onSubmit={(e) => {
e.preventDefault()
const form = e.target as HTMLFormElement
const formData = new FormData(form)
const email = formData.get('email') as string
const password = formData.get('password') as string
login(email, password)
}}
>
<div className='input-group'>
<input
{...getEmailInputProps()}
className='email-input'
placeholder='Email address'
/>
</div>
<div className='input-group'>
<input
{...getPasswordInputProps()}
className='password-input'
placeholder='Password'
/>
</div>
<button {...getSubmitButtonProps()} className='submit-button'>
{isLoading ? 'Signing in...' : 'Sign In'}
</button>
{loginError && <div className='error'>{loginError.message}</div>}
{loginSuccess && <div className='success'>Login successful!</div>}
</form>
)}
</Login.Root>
)
}
import { View, TextInput, Pressable, Text } from 'react-native'
import { Login } from '@haus-storefront-react/authentication'
function CustomLoginForm() {
return (
<Login.Root
onLogin={(username) => console.log('Logged in:', username)}
onLoginError={(error) => console.error('Login failed:', error)}
>
{({
isLoading,
loginError,
loginSuccess,
login,
getEmailInputProps,
getPasswordInputProps,
getSubmitButtonProps,
}) => (
<View>
<TextInput {...getEmailInputProps()} placeholder='Email address' />
<TextInput
{...getPasswordInputProps()}
placeholder='Password'
secureTextEntry
/>
<Pressable
{...getSubmitButtonProps()}
onPress={() => login('email', 'password')}
>
<Text>{isLoading ? 'Signing in...' : 'Sign In'}</Text>
</Pressable>
{loginError && <Text>Error: {loginError.message}</Text>}
{loginSuccess && <Text>Login successful!</Text>}
</View>
)}
</Login.Root>
)
}
Custom Styling with asChild
- React
- React Native
import { Login } from '@haus-storefront-react/authentication'
function CustomStyledLoginForm() {
return (
<Login.Root>
<Login.Form asChild>
<form className='login-form'>
<Login.EmailInput asChild>
<input className='email-input' />
</Login.EmailInput>
<Login.PasswordInput asChild>
<input className='password-input' />
</Login.PasswordInput>
<Login.SubmitButton asChild>
<button className='submit-button'>Login</button>
</Login.SubmitButton>
</form>
</Login.Form>
</Login.Root>
)
}
import { View, TextInput, Pressable, Text } from 'react-native'
import { Login } from '@haus-storefront-react/authentication'
function CustomStyledLoginForm() {
return (
<Login.Root>
<Login.Form asChild>
<View>
<Login.EmailInput asChild>
<TextInput placeholder='Email' />
</Login.EmailInput>
<Login.PasswordInput asChild>
<TextInput placeholder='Password' secureTextEntry />
</Login.PasswordInput>
<Login.SubmitButton asChild>
<Pressable>
<Text>Login</Text>
</Pressable>
</Login.SubmitButton>
</View>
</Login.Form>
</Login.Root>
)
}
Complete Password Reset Flow
- React
- React Native
import {
RequestReset,
ResetPassword,
} from '@haus-storefront-react/authentication'
import { useState } from 'react'
function PasswordResetFlow() {
const [step, setStep] = useState<'request' | 'reset'>('request')
const [token, setToken] = useState<string | null>(null)
if (step === 'request') {
return (
<RequestReset.Root
onPasswordReset={(email) => {
console.log('Reset email sent to:', email)
// In a real app, extract token from email link
setToken('extracted-token-from-email')
setStep('reset')
}}
>
{({ isLoading, requestResetError, requestResetSuccess }) => (
<div className='password-reset'>
<h2>Reset Password</h2>
<p>Enter your email address and we'll send you a reset link.</p>
<RequestReset.Form>
<RequestReset.EmailInput
className='form-input'
placeholder='Enter your email'
/>
<RequestReset.SubmitButton className='submit-btn'>
{isLoading ? 'Sending...' : 'Send Reset Link'}
</RequestReset.SubmitButton>
</RequestReset.Form>
{requestResetError && (
<div className='error'>{requestResetError.message}</div>
)}
{requestResetSuccess && (
<div className='success'>Reset link sent! Check your email.</div>
)}
</div>
)}
</RequestReset.Root>
)
}
if (step === 'reset' && token) {
return (
<ResetPassword.Root
token={token}
onReset={() => {
console.log('Password reset successful')
setStep('request')
setToken(null)
}}
>
{({ isLoading, resetPasswordError, resetPasswordSuccess }) => (
<div className='password-reset'>
<h2>Set New Password</h2>
<ResetPassword.Form token={token}>
<ResetPassword.PasswordInput
className='form-input'
placeholder='New password'
/>
<ResetPassword.PasswordConfirmationInput
className='form-input'
placeholder='Confirm new password'
/>
<ResetPassword.SubmitButton className='submit-btn'>
{isLoading ? 'Resetting...' : 'Reset Password'}
</ResetPassword.SubmitButton>
</ResetPassword.Form>
{resetPasswordError && (
<div className='error'>{resetPasswordError.message}</div>
)}
{resetPasswordSuccess && (
<div className='success'>Password reset successfully!</div>
)}
</div>
)}
</ResetPassword.Root>
)
}
return null
}
import { useState } from 'react'
import { View, Text, TextInput, Pressable } from 'react-native'
import {
RequestReset,
ResetPassword,
} from '@haus-storefront-react/authentication'
function PasswordResetFlow() {
const [step, setStep] = useState<'request' | 'reset'>('request')
const [token, setToken] = useState<string | null>(null)
if (step === 'request') {
return (
<RequestReset.Root
onPasswordReset={(email) => {
console.log('Reset email sent to:', email)
setToken('extracted-token-from-email')
setStep('reset')
}}
>
{({ isLoading, requestResetError, requestResetSuccess }) => (
<View>
<Text>Reset Password</Text>
<Text>Enter your email address and we'll send you a reset link.</Text>
<RequestReset.Form asChild>
<View>
<RequestReset.EmailInput asChild>
<TextInput placeholder='Enter your email' />
</RequestReset.EmailInput>
<RequestReset.SubmitButton asChild>
<Pressable>
<Text>{isLoading ? 'Sending...' : 'Send Reset Link'}</Text>
</Pressable>
</RequestReset.SubmitButton>
</View>
</RequestReset.Form>
{requestResetError && (
<Text>Error: {requestResetError.message}</Text>
)}
{requestResetSuccess && (
<Text>Reset link sent! Check your email.</Text>
)}
</View>
)}
</RequestReset.Root>
)
}
if (step === 'reset' && token) {
return (
<ResetPassword.Root
token={token}
onReset={() => {
console.log('Password reset successful')
setStep('request')
setToken(null)
}}
>
{({ isLoading, resetPasswordError, resetPasswordSuccess }) => (
<View>
<Text>Set New Password</Text>
<ResetPassword.Form token={token} asChild>
<View>
<ResetPassword.PasswordInput asChild>
<TextInput placeholder='New password' secureTextEntry />
</ResetPassword.PasswordInput>
<ResetPassword.PasswordConfirmationInput asChild>
<TextInput
placeholder='Confirm new password'
secureTextEntry
/>
</ResetPassword.PasswordConfirmationInput>
<ResetPassword.SubmitButton asChild>
<Pressable>
<Text>{isLoading ? 'Resetting...' : 'Reset Password'}</Text>
</Pressable>
</ResetPassword.SubmitButton>
</View>
</ResetPassword.Form>
{resetPasswordError && (
<Text>Error: {resetPasswordError.message}</Text>
)}
{resetPasswordSuccess && (
<Text>Password reset successfully!</Text>
)}
</View>
)}
</ResetPassword.Root>
)
}
return null
}
Made with ❤️ by Haus Tech Team