@boostinc/common-components

A premium React UI component library with 44 polished components, light/dark theming, and full TypeScript support. Available via npm or CDN.

🚀 Installation

npm / yarn / pnpm

# npm
npm install @boostinc/common-components

# yarn
yarn add @boostinc/common-components

# pnpm
pnpm add @boostinc/common-components

Peer dependencies: react >= 17 and react-dom >= 17

CDN (UMD)

<!-- React (peer dep) -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Boost Components -->
<link rel="stylesheet" href="https://unpkg.com/@boostinc/common-components/dist/style.css" />
<script src="https://unpkg.com/@boostinc/common-components/dist/index.umd.js"></script>

<script>
  // All components are available on the global `BoostComponents` object
  const { Button, ThemeProvider } = BoostComponents;
</script>

⚡ Quick Start

import { ThemeProvider, Button, Input, Modal } from '@boostinc/common-components';
import '@boostinc/common-components/style.css';

function App() {
  return (
    <ThemeProvider defaultTheme="light">
      <Button variant="primary" size="md">
        Get Started
      </Button>
    </ThemeProvider>
  );
}

🔐 Auth Core (hooks + state + route guards)

The library now includes a lightweight auth core inspired by refine-style usage patterns.

Exports

• AuthProvider
• useAuth
• useAuthorization
• useProtectedRoute
• usePublicRoute
• ProtectedRoute
• PublicRoute
• AuthorizationGate

Basic setup

import {
  AuthProvider,
  useAuth,
  ProtectedRoute,
  PublicRoute,
  AuthorizationGate,
} from '@boostinc/common-components';

function LoginButton() {
  const auth = useAuth();

  return (
    <button
      onClick={() =>
        auth.login({
          user: { id: 1, name: 'Admin User' },
          token: 'jwt-token',
          roles: ['admin'],
          permissions: ['posts.read', 'posts.write'],
        })
      }
    >
      Login
    </button>
  );
}

function App() {
  return (
    <AuthProvider persistence="localStorage" persistKey="app.auth">
      <ProtectedRoute redirectTo="/login">
        <AuthorizationGate permissionsAny={['posts.write']} fallback={<div>No access</div>}>
          <div>Private admin content</div>
        </AuthorizationGate>
      </ProtectedRoute>

      <PublicRoute redirectTo="/dashboard">
        <LoginButton />
      </PublicRoute>
    </AuthProvider>
  );
}

Notes

• Works with any router: pass a custom navigate callback to ProtectedRoute / PublicRoute, or allow default browser redirects.
• Supports persisted auth state (localStorage, sessionStorage, or none).
• Supports role + permission checks plus custom predicate-based authorization.

🧠 Redux Core Setup

Common Redux Toolkit setup helpers are included to avoid repeating boilerplate.

Exports

• ReduxProvider
• createAppStore
• createReduxHooks
• createResettableSlice

Quick setup

import React from 'react';
import {
  ReduxProvider,
  createAppStore,
  createReduxHooks,
  createResettableSlice,
} from '@boostinc/common-components';

const counterSlice = createResettableSlice({
  name: 'counter',
  initialState: { value: 0 },
  reducers: {
    increment: (state) => {
      state.value += 1;
    },
    decrement: (state) => {
      state.value -= 1;
    },
  },
});

const store = createAppStore({
  reducer: {
    counter: counterSlice.reducer,
  },
});

type RootState = ReturnType<typeof store.getState>;
type AppDispatch = typeof store.dispatch;

const { useAppDispatch, useAppSelector } = createReduxHooks<RootState, AppDispatch>();

function Counter() {
  const value = useAppSelector((state) => state.counter.value);
  const dispatch = useAppDispatch();

  return (
    <div>
      <button onClick={() => dispatch(counterSlice.actions.decrement())}>-</button>
      <span>{value}</span>
      <button onClick={() => dispatch(counterSlice.actions.increment())}>+</button>
      <button onClick={() => dispatch(counterSlice.actions.resetState())}>Reset</button>
    </div>
  );
}

export default function App() {
  return (
    <ReduxProvider store={store}>
      <Counter />
    </ReduxProvider>
  );
}

Notes

• createAppStore wraps configureStore with sensible defaults.
• createReduxHooks gives typed selector/dispatch/store hooks per app.
• createResettableSlice adds a built-in resetState action to any slice.

📦 Components

| Component | Description | |---|---| | Button | Primary, secondary, outline, ghost, danger; sizes sm/md/lg; loading & disabled states | | Input | Text/password/email/search; left/right icons; label & validation states | | Textarea | Auto-resize, character count, validation states | | Select | Native dropdown with custom styling; placeholder & options | | Checkbox | Custom visual, indeterminate state, label | | RadioGroup | Grouped radio buttons; horizontal/vertical | | Toggle | On/off switch; sizes sm/md/lg | | Badge | 6 color variants; dot indicator; sizes | | Avatar | Image/initials fallback; online status dot | | Card | Header/body/footer slots; hoverable; bordered/shadow variants | | Modal | Portal-based; escape/overlay close; sizes sm–xl | | ToastProvider / useToast | Context-based toasts; auto-dismiss; position options | | Tooltip | Top/right/bottom/left; hover/focus trigger | | Tabs | Horizontal/vertical; controlled & uncontrolled | | Accordion | Single/multi expand; animated collapse | | Spinner | Sizes sm/md/lg; full-screen overlay mode | | Alert | Info/success/warning/error; dismissible | | Breadcrumbs | Accessible breadcrumb navigation with links or actions | | Divider | Horizontal/vertical separators with optional labels | | EmptyState | Placeholder layouts with icon, description, and actions | | Progress | Determinate progress bars with labels, values, and striped states | | Skeleton | Text, rectangular, and circular loading placeholders | | Chip | Compact tags for filters, status, and inline actions | | Drawer | Side panel overlay for navigation and contextual workflows | | Pagination | Page navigation with ellipsis, boundary, and controlled modes | | DataTable | Sortable, selectable data grids with loading and empty states | | Autocomplete | Searchable suggestion input with keyboard navigation | | Stepper | Multi-step progress indicator with clickable flows | | Menu | Accessible dropdown menu with keyboard support and placements | | ButtonGroup | Group multiple actions in horizontal or vertical attached layouts | | FloatingActionButton | Circular high-emphasis action button with extended mode | | NumberField | Numeric input with increment/decrement controls | | Slider | Continuous value selector with optional live value display | | Rating | Star rating input with configurable precision | | AppBar | Top application bar for branding, navigation, and actions | | Dashboard | Complete dashboard page shell with sidebar, topbar, stats, widgets, activity feed, and table section | | Paper | Surface container with elevation or outlined variants | | Link | Themed text links with underline controls | | Box | Polymorphic primitive wrapper with spacing and surface options | | Container | Responsive width wrapper with max-size presets | | Stack | Flex layout helper with directional spacing | | Backdrop | Full-screen overlay for modal states and focus control | | Portal | Render children outside normal DOM hierarchy | | Popover | Anchored floating panel with placement and outside-click close | | ClickAwayListener | Utility wrapper that fires callbacks on outside clicks | | useMediaQuery | Responsive utility hook for viewport-based UI behavior |

| KanbanBoard | Drag-and-drop workflow board with columns, priorities, and assignee metadata | | OrgChart | Hierarchical organizational chart tree with connectors and avatars | | LineChart | SVG line chart with optional area fill, grid lines, and point markers | | AreaChart | Trend area graph with gradient fill and point markers | | BarChart | Multi-series style bar visualization with custom colors and values | | DonutChart | Circular segmented donut chart with center value and legend | | RadarChart | Multi-axis radar/spider chart for comparative category metrics | | HeatmapChart | Matrix heatmap for dense intensity data across X/Y dimensions | | SparklineChart | Compact inline trend graph for dashboards and KPI cards | | GanttChart | Timeline graph for planning tasks with start/end dates and progress | | MultiLineChart | Interactive multi-series line graph with legend toggles | | GroupedBarChart | Multi-series grouped bar graph for category comparisons | | StackedBarChart | Stacked bar chart for composition and total analysis | | PieChart | Interactive pie graph with hover focus and legend toggles | | ChatAssistant | ChatGPT-style conversational component with async replies, typing state, and suggestions | | SubscriptionManager | Subscription billing UI with plans, usage meters, and cancellation action | | FormBuilder | Dynamic schema-driven form builder with text/select/switch/textarea fields | | ProfileSettings | Account profile editor with avatar upload and timezone/bio controls | | SettingsPanel | Sectioned application settings UI with toggles, selects, and text values | | EventsManager | Event management module with create/search/filter/delete workflows |

All components

Getting started Components All components Inputs Autocomplete Button Button Group Checkbox Floating Action Button Number Field New Radio Group Rating Select Slider Switch Text Field Transfer List Toggle Button Data display Avatar Badge Chip Divider Icons Material Icons List Table Tooltip Typography Feedback Alert Backdrop Dialog Progress Skeleton Snackbar Surfaces Accordion App Bar Card Paper Navigation Bottom Navigation Breadcrumbs Drawer Link Menu Pagination Speed Dial Stepper Tabs Layout Box Container Grid GridLegacy Deprecated Stack Image List Utils Click-Away Listener CSS Baseline InitColorSchemeScript Modal No SSR Popover Popper Portal Textarea Autosize Transitions useMediaQuery MUI X Data Grid Date and Time Pickers Charts Tree View

🎛 Styling Overrides

Every component supports a root className, and non-native wrappers also expose a root style prop for direct overrides.

MUI-style compatibility components exported from MuiCompat (for example TransferList, DataGrid, DatePicker, TimePicker, DateTimePicker, Charts, and TreeView) also expose root-level external styling hooks such as className and style, with additional slot class props on complex components.

Form controls expose additional slot-level styling hooks for the parts teams normally need to customize:

| Component | Extra styling hooks | |---|---| | Input | wrapperStyle, containerClassName, inputClassName, labelClassName, helperClassName | | Select | wrapperStyle, selectClassName, labelClassName, helperClassName | | Textarea | wrapperStyle, textareaClassName, labelClassName, footerClassName | | Checkbox | wrapperStyle, inputClassName, labelClassName | | RadioGroup | style, itemClassName, groupLabelClassName | | Toggle | wrapperStyle, inputClassName, trackClassName, labelClassName | | Modal | style, overlayClassName, bodyClassName | | Tabs | style, listClassName, panelClassName | | Tooltip | style, tooltipClassName | | ToastProvider | className, style | | Autocomplete | style, wrapperStyle, inputClassName, labelClassName, helperClassName, listClassName, optionClassName | | DataTable | style, headerClassName, rowClassName, cellClassName | | Stepper | style, stepClassName | | Menu | style, triggerClassName, panelClassName, itemClassName | | NumberField | wrapperStyle | | Slider | Standard className and native input props | | Rating | style | | AppBar | Standard className and native header props | | Paper | Standard className and native div props | | Link | Standard className and native anchor props | | Box | Standard className, style, and spacing props | | Container | Standard className and native div props | | Stack | Standard className, style, and flex props | | Backdrop | style, className | | Popover | style, className |

<Input
  label="Workspace name"
  containerClassName="my-brand-input"
  inputClassName="my-brand-input__field"
  wrapperStyle={{ maxWidth: 360 }}
/>

You can also target the library's stable boost-* CSS class names from your application stylesheet.

🎨 Theming

Wrap your app in <ThemeProvider> to enable CSS variable theming:

import { ThemeProvider, useTheme } from '@boostinc/common-components';

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <MyContent />
    </ThemeProvider>
  );
}

function MyContent() {
  const { theme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>Current: {theme}</button>;
}

Custom CSS variables

Override any design token via CSS:

:root {
  --boost-color-primary-500: #8b5cf6;
  --boost-color-primary-600: #7c3aed;
  --boost-radius-md: 0.75rem;
}

🛠 Development

npm install
npm run dev      # Vite dev server
npm run build    # Build ESM + CJS + UMD bundles
npm run typecheck # TypeScript validation

npm run dev launches the local showcase in the demo/ folder.

📁 Build Output

| File | Format | Usage | |---|---|---| | dist/index.es.js | ESM | import in bundlers | | dist/index.cjs.js | CJS | require() in Node | | dist/index.umd.js | UMD | <script> tag / CDN | | dist/style.css | CSS | Styles (included automatically in JS for UMD) | | dist/index.d.ts | Types | TypeScript declarations |

📄 License

MIT