doct-ui-auth-kit

A composable React auth SDK for building authentication and onboarding experiences. Built with React composition patterns for maximum flexibility and scalability.

Install

npm install doct-ui-auth-kit

Peer dependencies (install in your app if not already present):

npm install react react-dom docthub-core-components react-hook-form zod

Global styles

Import the kit CSS once in your app (e.g. in main.tsx or _app.tsx) so Tailwind and base styles apply:

import 'doct-ui-auth-kit/style.css';

If you use docthub-core-components, import its styles first, then the auth kit:

import 'docthub-core-components/style.css';
import 'doct-ui-auth-kit/style.css';

Required static assets

When using MainLoginPage or AuthLayoutWrapper with layoutType="withSlider", the kit references static paths that are served from your app’s public/ folder. The published npm package does not include these files, so you must add them yourself.

| Asset | Path in your app | Used for | |-------|------------------|----------| | Logo | public/main-logo.svg | Main login page logo (or pass a custom logo prop to AuthLayoutWrapper) | | Slider images | public/slider/slide-1.png … public/slider/slide-5.png | Marketing slider on the left panel (or pass custom sliderImages to AuthLayoutWrapper) |

To get the default assets: copy from this repo’s public/main-logo.svg and public/slider/*.png into your app’s public/ (and public/slider/) if you have the kit source. Otherwise use your own logo and slider images. You can also override at runtime by passing the logo and sliderImages props to AuthLayoutWrapper (or equivalent) where the API supports it.

Consumer imports

Install the package and import components, layouts, and types from the library:

import {
  AuthLayout,
  OtpVerification,
  type OtpVerificationProps,
} from 'doct-ui-auth-kit';

function Example() {
  const handleSubmit: OtpVerificationProps['onSubmit'] = (otp) => {
    // handle OTP
  };

  return (
    <AuthLayout.Root variant="mobile" maxWidth="sm">
      <AuthLayout.Main>
        <AuthLayout.Body>
          <OtpVerification
            mode="phone"
            recipientDisplay="+91 9825910X0X"
            onSubmit={handleSubmit}
          />
        </AuthLayout.Body>
      </AuthLayout.Main>
    </AuthLayout.Root>
  );
}

Components

AuthLayout

A compound component system for authentication pages using composition pattern. Provides consistent spacing, responsive centering, and flexible content organization.

Design Philosophy

The AuthLayout uses compound components (slot-based pattern) to provide maximum flexibility. Each slot can be independently composed, reordered, or omitted based on your needs.

Usage

import { AuthLayout } from '@/components/layout';

<AuthLayout.Root variant="desktop" maxWidth="md">
  <AuthLayout.Header>
    <EnterpriseLoginBadge />
  </AuthLayout.Header>
  <AuthLayout.Main>
    <AuthLayout.Logo>
      <img src="/logo.svg" alt="Docthub" />
    </AuthLayout.Logo>
    <AuthLayout.Title>
      <h1>The Healthcare Career App</h1>
    </AuthLayout.Title>
    <AuthLayout.Description>
      <p>Continue to Signup, If you already have an account we'll log you in.</p>
    </AuthLayout.Description>
    <AuthLayout.Body>
      <button>Continue with Mobile</button>
      <button>Continue with Email</button>
    </AuthLayout.Body>
  </AuthLayout.Main>
  <AuthLayout.Footer>
    <p>Terms and Privacy links</p>
  </AuthLayout.Footer>
</AuthLayout.Root>

Components

AuthLayout.Root

• Main container providing layout context to all child slots
• Props:
  • variant?: 'mobile' | 'desktop' - Layout variant (default: 'mobile')
  • maxWidth?: 'sm' | 'md' | 'lg' - Content width constraint (default: 'sm')
  • className?: string - Additional root className
  • contentClassName?: string - Additional content wrapper className

AuthLayout.Header

• Optional header slot, renders top-right in desktop variant, above logo in mobile

AuthLayout.Main

• Main content wrapper that centers and constrains width of inner slots

AuthLayout.Logo

• Logo slot with centered alignment

AuthLayout.Title

• Title slot with centered alignment

AuthLayout.Description

• Description slot with centered alignment

AuthLayout.Body

• Main content area for forms, buttons, etc. with vertical spacing

AuthLayout.Footer

• Optional footer slot for terms, privacy links, etc.

Benefits of Composition Pattern

• Flexible ordering: Rearrange slots as needed without prop drilling
• Selective rendering: Only include the slots you need
• Type safety: Each slot has its own typed props
• Extensibility: Easy to add custom slots without breaking existing APIs
• Better DX: Clear component hierarchy in JSX

MainLayout

Two-panel layout for authentication pages with marketing content on the left and auth content on the right.

Usage

import { MainLayout } from '@/components/layout';
import { AuthLayout } from '@/components/layout';

<MainLayout
  sliderImages={['/image1.jpg', '/image2.jpg', '/image3.jpg']}
  sliderAutoPlayInterval={5000}
  ctaText="Get Healthcare Career App Now!"
>
  <AuthLayout.Root variant="desktop" maxWidth="sm" className="bg-transparent">
    <AuthLayout.Header>
      <EnterpriseLoginBadge />
    </AuthLayout.Header>
    <AuthLayout.Main>
      <AuthLayout.Logo>...</AuthLayout.Logo>
      <AuthLayout.Title>...</AuthLayout.Title>
      <AuthLayout.Body>...</AuthLayout.Body>
    </AuthLayout.Main>
    <AuthLayout.Footer>...</AuthLayout.Footer>
  </AuthLayout.Root>
</MainLayout>

Props

• sliderImages?: string[] - Array of image URLs for the slider (default: [])
• sliderAutoPlayInterval?: number - Auto-play interval in milliseconds (default: 5000, 0 to disable)
• ctaText?: ReactNode | null - Call-to-action text, set to null to hide
• className?: string - Additional root className
• marketingClassName?: string - Additional className for left marketing panel
• contentClassName?: string - Additional className for right content panel
• children: ReactNode - Auth content (typically AuthLayout.Root)

ImageSlider

Image carousel component with indicator dots. Supports both controlled and uncontrolled modes.

Usage (Uncontrolled)

import { ImageSlider } from '@/components/layout';

<ImageSlider
  images={['/image1.jpg', '/image2.jpg']}
  autoPlayInterval={3000}
  onSlideChange={(index) => console.log('Slide changed to', index)}
/>

Usage (Controlled)

import { ImageSlider } from '@/components/layout';
import { useState } from 'react';

const [activeIndex, setActiveIndex] = useState(0);

<ImageSlider
  images={['/image1.jpg', '/image2.jpg']}
  activeIndex={activeIndex}
  onSlideChange={setActiveIndex}
  onNavigate={setActiveIndex}
  autoPlayInterval={5000}
/>

Props

• images: string[] - Array of image URLs
• autoPlayInterval?: number - Auto-play interval in ms (default: 5000, 0 to disable)
• className?: string - Additional root className
• hideIndicators?: boolean - Hide built-in indicators (default: false)
• onSlideChange?: (index: number) => void - Callback when slide changes
• activeIndex?: number - Controlled active index
• onNavigate?: (index: number) => void - Callback for manual navigation in controlled mode

Migration Guide

If you were using the old prop-based AuthLayout, here's how to migrate:

Before (Old API)

<AuthLayout
  header={<Header />}
  logo={<Logo />}
  title="Welcome"
  description="Sign in to continue"
  footer={<Footer />}
>
  <LoginForm />
</AuthLayout>

After (New Compound API)

<AuthLayout.Root variant="mobile" maxWidth="sm">
  <AuthLayout.Header>
    <Header />
  </AuthLayout.Header>
  <AuthLayout.Main>
    <AuthLayout.Logo>
      <Logo />
    </AuthLayout.Logo>
    <AuthLayout.Title>Welcome</AuthLayout.Title>
    <AuthLayout.Description>Sign in to continue</AuthLayout.Description>
    <AuthLayout.Body>
      <LoginForm />
    </AuthLayout.Body>
  </AuthLayout.Main>
  <AuthLayout.Footer>
    <Footer />
  </AuthLayout.Footer>
</AuthLayout.Root>

Documentation

See Storybook for interactive examples and visual documentation:

npm run storybook

Publishing to npm

1. Login (one-time): npm login
2. Build (runs automatically on publish): npm run build
3. Publish:
   • First release: npm publish
   • Scoped package (if name is taken): set "name": "@your-org/doct-ui-auth-kit" then npm publish --access public
4. Use in another project: npm install doct-ui-auth-kit