React Component Library Template

A production-ready React component library template with common UI primitives, utilities and examples built with Vite and Tailwind.

Overview

• Library location: src/common/components/
• App-specific demo components: src/components/
• Utilities: src/utils/ (includes helpers.js with cn helper)
• Hooks: src/hooks/ (useForm, useOnClickOutside, useId, etc.)
• State & data: src/service/ (Redux store, React Query client)

Quick start

1. Install

npm install

2. Development

npm run dev

3. Build (app)

npm run build

4. Library build (bundles src/common/components/index.js)

npm run build:lib

5. Preview production build

npm run preview

Project structure (relevant)

• src/
  • common/
    • components/ — reusable UI components (library); export barrel: src/common/components/index.js
      • Accordion/
      • Alert/
      • Avatar/
      • AvatarBadge/ — presence/status dot for Avatar
      • AvatarGroup/
      • Badge/
      • Breadcrumb/
      • Button/
      • ButtonGroup/ — grouped/segmented buttons
      • Card/
      • Carousel/
      • Checkbox/
      • Chart/ — thin adapter for Chart.js (optional peer dep)
      • CircularProgress/ — SVG circular progress
      • Collapse/ — accessible collapsible panel
      • DatePicker/ — calendar date / range picker
      • DialogLayout/
      • Drawer/ — slide-over / side panel
      • Dropdown/
      • EmptyState/ — standardized empty/no-data UI
      • ErrorBoundary/ — React error boundary wrapper
      • Fab/ — Floating Action Button
      • FilePreview/ — image preview + simple crop helper
      • FileUploader/ — drag/drop file upload
      • Form/
      • Grid/
      • Hero/
      • Icon/
      • Input/
        • MaskedInput.jsx — input masking helper
      • InputGroup/ — input prefix/suffix grouping
      • Loading/
      • Modal/
      • Navbar/
      • Pagelayout/
      • Pagination/
      • Popover/
      • Progress/ — linear progress bar
      • RadioGroup/
      • Section/
      • Select/
      • Skeleton/
      • Sidebar/
      • Spinner/
      • Stepper/
      • Switch/
      • Table/
      • Tabs/
      • Tag/ — chip / label component
      • TagGroup/ — wrapper for multiple tags
      • Textarea/
      • TimePicker/ — time selection input
      • Timeline/
      • Tooltip/
      • Notification/ — NotificationProvider, Toast, ToastContainer, useToast
      • Portal/ — DOM portal utility
      • FocusTrap/ — small focus trap for modal accessibility
      • VisuallyHidden/ — sr-only helper
      • SkipToContent/ — skip link utility
      • index.js — library export entry (used by library build)
  • components/ — app-specific demo components (examples & app-only)
    • Toast/ — app demo toast (consider consolidating with library Notification)
  • hooks/
    • useForm.js
    • useCommon.js (useToggle, useLocalStorage, useDebounce, ...)
    • useOnClickOutside.js
    • useId.js
  • utils/
    • helpers.js (cn)
  • service/
    • store.js
    • queryClient.js
  • pages/
  • App.jsx
  • main.jsx

New / Notable components added since initial template

• DatePicker (calendar with optional range support)
• TimePicker (selectable time list, 12/24h support)
• Combobox (ARIA-compliant autocomplete)
• MultiSelect (chips/tags + search)
• MaskedInput (simple mask patterns)
• FilePreview (image preview + crop helper)
• FileUploader (drag/drop uploader with previews)
• Drawer (slide-over alternative to modal)
• EmptyState (standardized empty-state UI)
• ErrorBoundary (UI wrapper for runtime errors)
• Fab (Floating Action Button)
• Chart (thin adapter, optional Chart.js)
• Tag / TagGroup
• InputGroup
• ButtonGroup / IconButton
• Progress / CircularProgress
• AvatarBadge
• Portal / FocusTrap / VisuallyHidden / SkipToContent
• useOnClickOutside, useId hooks

Components (detailed)

Layout Components

• PageLayout (Pagelayout)

  • Main layout wrapper integrating Navbar and Sidebar.
  • Location: src/common/components/Pagelayout/

• Navbar, Sidebar, Footer

  • Responsive navigation / layout primitives.
  • Locations: src/common/components/Navbar/, src/common/components/Sidebar/, src/common/components/Footer/

Overlay & Navigation

• Modal, Drawer, Popover
  • Modal: accessible dialog using Portal + FocusTrap.
  • Drawer: slide-over side panel for mobile/side content.
  • Popover: interactive panel with placement/trigger options.

Form Components

• Form

  • Wrapper that prevents default submit and delegates to onSubmit.
  • Location: src/common/components/Form/Form.jsx

• FormField

  • Label + control wrapper with help/error text and aria-describedby.
  • Location: src/common/components/Form/FormField.jsx

• Input, MaskedInput, InputGroup, Select, Checkbox, RadioGroup, Textarea, Button

  • Standard form controls with composition-friendly props.
  • MaskedInput supports simple masks like (999) 999-9999.

Advanced Form Controls

• Combobox (autocomplete / typeahead, keyboard accessible)
• MultiSelect (tags + search)
• DatePicker & TimePicker (date/time selection, range support)

Data & UI Components

• Card, Table, Pagination, Tabs, Badge, Alert, Modal, DialogLayout
  • Reusable content display building blocks.

Controls & Feedback

• Spinner, Loading, CircularProgress, Progress

  • Low-level and higher-level loading indicators.

• Alert

  • Inline contextual feedback.

• Tag, TagGroup

  • Compact labels / chips with optional remove action.

File handling

• FileUploader

  • Drag & drop, multiple, previews, size limits.

• FilePreview

  • Lightweight image preview + simple crop; integrate a dedicated crop library for production.

Utilities & Accessibility

• Icon: central icon component and icon set.
• Portal: mount overlays to body or a target element.
• FocusTrap: lightweight focus management for dialogs.
• VisuallyHidden: sr-only wrapper.
• SkipToContent: accessibility skip link.
• Hooks: useOnClickOutside, useId (SSR-friendly stable ids).

Notification / Toast system

• Library-level toast system:
  • Provider: src/common/components/Notification/NotificationProvider.jsx
  • Hook: src/common/components/Notification/useToast.js
  • UI: Toast.jsx, ToastContainer.jsx

To enable global toasts wrap your app with the provider (example in src/main.jsx):

import NotificationProvider from "./common/components/Notification/NotificationProvider";

createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <Provider store={store}>
      <QueryClientProvider client={queryClient}>
        <NotificationProvider>
          <App />
        </NotificationProvider>
      </QueryClientProvider>
    </Provider>
  </React.StrictMode>
);

Note: the repo also contains an app-specific toast at src/components/Toast/Toast.jsx. Consider consolidating with the library Notification system for consistent UX.

Usage examples (selected)

Button

import { Button } from "./common/components";

<Button variant="primary" size="large">
  Click Me
</Button>;

IconButton / ButtonGroup

import IconButton from "./common/components/IconButton/IconButton";
import ButtonGroup from "./common/components/ButtonGroup/ButtonGroup";

<IconButton icon="search" ariaLabel="Search" />
<ButtonGroup>
  <Button>Left</Button>
  <Button>Right</Button>
</ButtonGroup>

Form

import Form from "./common/components/Form/Form";
import FormField from "./common/components/Form/FormField";
import Input from "./common/components/Input/Input";

<Form onSubmit={(values) => console.log(values)}>
  <FormField label="Email" name="email" required>
    <Input name="email" placeholder="Your email" />
  </FormField>
  <Button type="submit">Submit</Button>
</Form>;

Combobox / MultiSelect

import Combobox from "./common/components/Combobox/Combobox";
import MultiSelect from "./common/components/MultiSelect/MultiSelect";

<Combobox items={[{value: '1', label: 'One'}]} onChange={(v)=>console.log(v)} />
<MultiSelect options={[{value:'a',label:'A'}]} value={['a']} onChange={(vals)=>console.log(vals)} />

DatePicker / TimePicker

import DatePicker from "./common/components/DatePicker/DatePicker";
import TimePicker from "./common/components/TimePicker/TimePicker";

<DatePicker value={null} onChange={(d)=>console.log(d)} range />
<TimePicker value="09:30" onChange={(t)=>console.log(t)} step={15} use12Hours />

FileUploader / FilePreview

import FileUploader from "./common/components/FileUploader/FileUploader";
import FilePreview from "./common/components/FilePreview/FilePreview";

<FileUploader accept="image/*" multiple maxFiles={5} onChange={(files)=>console.log(files)} />
<FilePreview file={someFile} onCrop={(blob)=>console.log(blob)} />

Accessibility conventions

• Tooltips: role="tooltip" and visible text for screen readers.
• Toasts: role="status" and aria-live="polite".
• FormField: aria-describedby links help/error text when present.
• Overlays: Modal/Drawer use Portal + FocusTrap; Escape and backdrop click handlers available.
• useId hook: SSR-friendly stable IDs for accessibility attributes.

Styling & Theming

• Tailwind CSS is used for styling (configured in tailwind.config.js).
• Components accept className and spread remaining props to the root element for composition.
• cn helper in src/utils/helpers.js centralizes conditional class name composition.

Packaging & exports

• Library entry point: src/common/components/index.js — ensure every component folder you want to publish is exported from this barrel file before running npm run build:lib.
• Vite config points to the library entry for npm run build:lib. React and react-dom are marked external for library builds.

Optional / peer dependencies

• Chart component dynamically requires chart.js/auto. Install chart.js to enable charts:

  npm install chart.js

Testing & linting

• Run unit tests and lints before committing:

npm run test
npm run lint

Development notes and conventions

• Functional React components with JSDoc-style comments where helpful.
• Keep components small, composable and stateless where possible.
• Prefer composition over polymorphic props for custom content (e.g., children for custom icon SVGs or custom toast content).
• Add unit tests for component logic and snapshot tests for UI where appropriate.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

• MIT (see LICENSE file)

Acknowledgments

• React
• Tailwind CSS
• Material-UI (design inspiration)
• Open-source community

Advanced / Additional Notes

Environment variables

• Use .env for configuration:

VITE_API_BASE_URL=https://api.example.com
VITE_APP_NAME=My Component Library

ESLint and TypeScript

• TypeScript is supported. For production apps, enable TypeScript and type-aware lint rules. See Vite React TS template for integration guidance: https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts

This README reflects the current code layout and recent component additions. Verify src/common/components/index.js exports every component you intend to publish and wrap your application with NotificationProvider if you rely on the global toast system.