@bpfdev/oly-ui

npm: @bpfdev/oly-ui · private (requires membership of the @bpfdev/oly-ui npm org)

Live docs: falcon-oly-storybook.web.app — interactive component playground with controls, code snippets, and prop tables for every exported component.

A production-ready React component library built on top of MUI, designed for data-heavy dashboards and enterprise UIs. Ships with full TypeScript types, tree-shakeable ESM + CJS bundles, and an optional Tailwind CSS preset.

Installation

npm install @bpfdev/oly-ui

Peer dependencies

The following packages must be installed in your project:

npm install react react-dom \
  @mui/material @mui/icons-material @mui/x-data-grid @mui/utils \
  @emotion/react @emotion/styled \
  @iconify/react

Quick start

Wrap your application (or Storybook preview) with FalconThemeProvider to apply the Falcon design tokens:

import { FalconThemeProvider } from '@bpfdev/oly-ui';

function App() {
  return (
    <FalconThemeProvider
      settings={{
        mode: 'light',
        direction: 'ltr',
        appBarBlur: true,
        navCollapsed: false,
      }}
    >
      {/* your app */}
    </FalconThemeProvider>
  );
}

Components

For live interactive examples, prop tables, and copy-paste code snippets for every component, visit the Storybook documentation →

FalconButton

A MUI Button wrapper with a built-in loading state.

import { FalconButton } from '@bpfdev/oly-ui';

<FalconButton variant="contained" loading={isSubmitting} onClick={handleSave}>
  Save
</FalconButton>;

| Prop | Type | Default | Description | | ----------- | ------------------------------------- | ------------- | --------------------------------------- | | variant | 'contained' \| 'outlined' \| 'text' | 'contained' | MUI button variant | | size | 'small' \| 'medium' \| 'large' | 'large' | Button size | | loading | boolean | false | Shows a spinner and disables the button | | disabled | boolean | — | Disables the button | | fullWidth | boolean | true | Stretches to container width | | type | 'submit' \| 'button' \| 'reset' | 'submit' | HTML button type |

FalconMultiSelect

A controlled multi-select autocomplete with apply/clear actions.

import { FalconMultiSelect } from '@bpfdev/oly-ui';
import type { FalconMultiSelectOption } from '@bpfdev/oly-ui';

const regions: FalconMultiSelectOption[] = [
  { id: 1, name: 'North' },
  { id: 2, name: 'South' },
  { id: 3, name: 'East' },
];

function Example() {
  const [selected, setSelected] = React.useState<FalconMultiSelectOption[]>([]);

  return (
    <FalconMultiSelect
      label="Region"
      list={regions}
      data={selected}
      setData={setSelected}
    />
  );
}

| Prop | Type | Description | | --------- | -------------------------------------------- | --------------------------------------- | | label | string | Placeholder / trigger label | | list | FalconMultiSelectOption[] | All available options | | data | FalconMultiSelectOption[] | Currently selected options (controlled) | | setData | (value: FalconMultiSelectOption[]) => void | Called when Apply or Clear is clicked |

FalconSelect

A single-value select built on MUI TextField.

import { FalconSelect } from '@bpfdev/oly-ui';

<FalconSelect
  label="Status"
  value={status}
  onChange={setStatus}
  options={['Active', 'Inactive', 'Pending']}
  clearable
/>;

| Prop | Type | Default | Description | | ----------- | ---------------------------------- | ------- | --------------------------- | | label | string | — | Field label | | value | string | — | Selected value (controlled) | | onChange | (value: string) => void | — | Change callback | | options | string[] \| FalconSelectOption[] | — | Options list | | disabled | boolean | false | Disables the field | | clearable | boolean | false | Adds a clear button |

FalconPagination

A combined page-number + page-size selector.

import { FalconPagination } from '@bpfdev/oly-ui';

<FalconPagination
  pageNo={page}
  setPageNo={setPage}
  perPage={rowsPerPage}
  setPerPage={setRowsPerPage}
  totalItems={totalCount}
  perPageOptions={[10, 25, 50]}
/>;

| Prop | Type | Default | Description | | ---------------- | --------------------- | -------------- | ----------------------------- | | pageNo | number | — | Current page (1-based) | | setPageNo | (n: number) => void | — | Page change callback | | perPage | number | — | Rows per page | | setPerPage | (n: number) => void | — | Rows-per-page change callback | | totalItems | number | — | Total record count | | perPageOptions | number[] | [10, 25, 50] | Dropdown options |

FalconTable

A thin wrapper around MUI X DataGrid with sensible defaults.

import { FalconTable } from '@bpfdev/oly-ui';
import type { GridColDef } from '@mui/x-data-grid';

const columns: GridColDef[] = [
  { field: 'id', headerName: 'ID', width: 90 },
  { field: 'name', headerName: 'Name', flex: 1 },
];

<FalconTable
  rows={data}
  columns={columns}
  getRowId={row => row.id}
  pageSizeOptions={[10, 25]}
  initialState={{ pagination: { paginationModel: { pageSize: 10 } } }}
/>;

| Prop | Type | Description | | ----------------- | ------------------------------ | -------------------------- | | rows | T[] | Row data array | | columns | GridColDef[] | Column definitions | | getRowId | (row: T) => string \| number | Row identity function | | pageSizeOptions | number[] | Page size options | | initialState | object | MUI DataGrid initial state |

FalconGrayButton

A secondary action button styled with a gray palette.

import { FalconGrayButton } from '@bpfdev/oly-ui';

<FalconGrayButton onClick={handleCancel}>Cancel</FalconGrayButton>;

ButtonWithIcon

A button that places an icon alongside a label.

import { ButtonWithIcon } from '@bpfdev/oly-ui';

<ButtonWithIcon icon={<AddIcon />} label="Add Item" onClick={handleAdd} />;

FalconSingleSwitch

A labeled toggle switch.

import { FalconSingleSwitch } from '@bpfdev/oly-ui';

<FalconSingleSwitch
  label="Enable notifications"
  checked={enabled}
  onChange={setEnabled}
/>;

FalconDIstrictFilter

A district-level filter selector.

import { FalconDIstrictFilter } from '@bpfdev/oly-ui';
import type { FalconDIstrictFilterOption } from '@bpfdev/oly-ui';

const districts: FalconDIstrictFilterOption[] = [
  { id: 1, name: 'Downtown' },
  { id: 2, name: 'Uptown' },
];

<FalconDIstrictFilter list={districts} data={selected} setData={setSelected} />;

FalconTicketFilter / FalconTicketColumsFilter

Ticket management filters for status, priority, and column visibility toggles.

import { FalconTicketFilter, FalconTicketColumsFilter } from '@bpfdev/oly-ui';

AdvancedFiltersDialog

A modal dialog for composing multi-criteria filter rules.

import { AdvancedFiltersDialog } from '@bpfdev/oly-ui';

HeatMapChartLegend

A color-scale legend for heat map charts.

import { HeatMapChartLegend } from '@bpfdev/oly-ui';
import type { HeatMapLegendItem } from '@bpfdev/oly-ui';

const items: HeatMapLegendItem[] = [
  { color: '#f7f7f7', label: 'Low' },
  { color: '#EE8B3A', label: 'High' },
];

<HeatMapChartLegend items={items} />;

ProgressBarNumber

A numeric value displayed alongside a progress bar.

import { ProgressBarNumber } from '@bpfdev/oly-ui';

<ProgressBarNumber value={72} max={100} label="Completion" />;

AddCommentInput

A text input designed for threaded comment submissions.

import { AddCommentInput } from '@bpfdev/oly-ui';

<AddCommentInput onSubmit={text => postComment(text)} />;

Tailwind CSS preset

If you use Tailwind, extend your config with the Falcon color tokens:

// tailwind.config.js
module.exports = {
  presets: [require('@bpfdev/oly-ui/tailwind.preset')],
  // ...
};

This exposes Falcon's primary palette as falcon-* utility classes (e.g. bg-falcon-500).

Note: The preset reads from the built dist/ folder — run npm run build in the package before using the preset in a fresh clone.

FalconThemeProvider settings

| Prop | Type | Default | Description | | -------------- | ------------------- | --------- | ---------------------------- | | mode | 'light' \| 'dark' | 'light' | Color scheme | | direction | 'ltr' \| 'rtl' | 'ltr' | Text direction | | appBarBlur | boolean | true | Frosted-glass app bar effect | | navCollapsed | boolean | false | Collapsed sidebar state |

Development

# build once
npm run build

# watch mode
npm run dev

# run tests
npm run test

# type-check without emitting
npm run typecheck

License

MIT © @bpfdev/oly-ui