@actabldesign/bellhop-react

React component library for the Bellhop design system. Provides React wrappers for Stencil web components and native React table primitives with TanStack Table integration.

Installation

npm install @actabldesign/bellhop-react

Peer Dependencies

npm install react react-dom

For table components with TanStack Table features:

npm install @tanstack/react-table

Usage

Stencil Component Wrappers

All 60+ Bellhop web components have React wrappers with full TypeScript support and proper event handling. Wrappers are auto-generated by @stencil/react-output-target and kept in sync with the core library automatically.

import { BhButton, BhInputText, BhCard } from '@actabldesign/bellhop-react';

function MyComponent() {
  return (
    <BhCard>
      <BhInputText
        label="Email"
        placeholder="Enter your email"
        onBhInput={(e) => console.log(e.detail)}
      />
      <BhButton hierarchy="primary" onBhClick={() => console.log('Clicked!')}>
        Submit
      </BhButton>
    </BhCard>
  );
}

Available Stencil Components

Every component in @actabldesign/bellhop-core has a corresponding React wrapper. Import them directly:

import { BhSidebar, BhAppbar, BhDataGrid } from '@actabldesign/bellhop-react';

Layout: BhAppbar, BhCard, BhCardHeader, BhCardFooter, BhContainer, BhContainerFooter, BhModal, BhModalHeader, BhModalActions, BhSidebar, BhAccordion, BhAccordionItem

Forms: BhInputText, BhInputPassword, BhInputNumber, BhInputAutocomplete, BhInputVerification, BhTextarea, BhCheckbox, BhCheckboxGroup, BhRadioButton, BhToggle, BhDropdown, BhLabel

Buttons: BhButton, BhButtonIcon

Data Display: BhDataGrid, BhBadge, BhBadgeDot, BhTag, BhAvatar, BhAvatarAdd, BhAvatarStacked, BhTooltip, BhPopover

Navigation: BhTabs, BhTabItem, BhBreadcrumbs, BhPagination, BhPageNavigation, BhNavItem, BhProductSwitcher, BhPropertySwitcher

Feedback: BhNotification, BhLoaderSpinner, BhEmptyState, BhSkeletonLoader

Date/Time: BhDatePicker, BhDateRangePicker, BhMonthPicker

Charts: BhBarChart, BhPieChart, BhTrendChart

Branding: BhLogoBox, BhFeaturedIcon, BhIllustrations

Event Handling

Bellhop React wrappers expose custom events as onBh* callback props. These are typed and provide event.detail payloads:

<BhButton onBhClick={(e) => console.log('clicked', e.detail)} />
<BhInputText onBhInput={(e) => setValue(e.detail)} />
<BhDropdown onBhChange={(e) => setSelected(e.detail)} />
<BhTabs onBhTabChange={(e) => setTab(e.detail)} />

React Wrappers vs Raw Web Components

Use React wrappers (recommended for React projects):

• Full TypeScript support with typed props and events
• Proper React event handling (no need for addEventListener)
• Ref forwarding works as expected
• Auto-generated, always in sync with bellhop-core

import { BhDataGrid } from '@actabldesign/bellhop-react';
<BhDataGrid data={rows} columns={cols} enableSorting />

Use raw web components only when:

• Working outside React (vanilla JS, Angular, Vue)
• Need direct DOM API access for advanced use cases

If using raw <bh-*> tags in React, add TypeScript support via @actabldesign/bellhop-core/react (see bellhop-core README).

Table Components

Table Primitives

Composable table components for building static and dynamic tables.

import {
  Table,
  TableWrapper,
  TableHead,
  TableBody,
  TableRow,
  TableHeaderCell,
  TableCell,
  TablePagination,
} from '@actabldesign/bellhop-react';

function BasicTable() {
  return (
    <TableWrapper>
      <Table size="default" variant="default" hoverable>
        <TableHead>
          <TableRow>
            <TableHeaderCell>Name</TableHeaderCell>
            <TableHeaderCell>Email</TableHeaderCell>
            <TableHeaderCell align="right">Actions</TableHeaderCell>
          </TableRow>
        </TableHead>
        <TableBody>
          <TableRow>
            <TableCell>John Doe</TableCell>
            <TableCell>[email protected]</TableCell>
            <TableCell align="right">Edit</TableCell>
          </TableRow>
        </TableBody>
      </Table>
    </TableWrapper>
  );
}

Table Primitive Components

| Component | Description | | ----------------- | ---------------------------------------------------------- | | Table | Main table element with size, variant, and styling options | | TableWrapper | Scrollable container for tables | | TableCaption | Accessible table caption | | TableHead | Table header section (<thead>) | | TableBody | Table body section (<tbody>) | | TableFooter | Table footer section (<tfoot>) | | TableRow | Table row with selection and expansion states | | TableHeaderCell | Header cell with sorting support | | TableCell | Data cell with alignment and truncation options | | TableEmpty | Empty state display for tables | | TableActionBar | Toolbar for bulk actions and filters | | TablePagination | Pagination controls |

DataTable (TanStack Table Integration)

A feature-rich data table component with built-in sorting, filtering, pagination, selection, expansion, grouping, and inline editing.

import { DataTable, ColumnDef } from '@actabldesign/bellhop-react';

interface User {
  id: string;
  name: string;
  email: string;
  role: string;
}

const columns: ColumnDef<User>[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'role', header: 'Role' },
];

function UsersTable({ users }: { users: User[] }) {
  return (
    <DataTable
      data={users}
      columns={columns}
      enableSorting
      enablePagination
      enableRowSelection
      pageSize={10}
      onSelectionChange={(selected) => console.log(selected)}
    />
  );
}

DataTable Props

| Prop | Type | Default | Description | | -------------------- | -------------------------------------- | ----------- | ------------------------- | | data | TData[] | required | Table data array | | columns | ColumnDef<TData>[] | required | Column definitions | | size | 'compact' \| 'default' \| 'relaxed' | 'default' | Row height | | variant | 'default' \| 'bordered' \| 'striped' | 'default' | Visual style | | enableSorting | boolean | true | Enable column sorting | | enableFiltering | boolean | false | Enable column filters | | enablePagination | boolean | true | Enable pagination | | enableRowSelection | boolean | false | Enable row selection | | enableExpanding | boolean | false | Enable row expansion | | enableGrouping | boolean | false | Enable row grouping | | enableEditing | boolean | false | Enable inline editing | | editMode | 'cell' \| 'row' | 'cell' | Editing mode | | pageSize | number | 10 | Initial page size | | stickyHeader | boolean | false | Sticky table header | | hoverable | boolean | true | Row hover effect | | loading | boolean | false | Loading state | | getRowId | (row, index) => string | - | Custom row ID accessor | | onSelectionChange | (rows) => void | - | Selection change callback | | onSortingChange | (sorting) => void | - | Sort change callback | | onRowClick | (row) => void | - | Row click callback | | onEditSave | (changes) => void | - | Edit save callback |

Column Helpers

import {
  createSelectColumn,
  createExpandColumn,
  createEditActionsColumn,
} from '@actabldesign/bellhop-react';

// Add selection checkbox column
const selectColumn = createSelectColumn<User>();

// Add expand/collapse column
const expandColumn = createExpandColumn<User>();

useDataTable Hook

For more control over the table instance:

import { useDataTable } from '@actabldesign/bellhop-react';

function CustomTable({ data, columns }) {
  const table = useDataTable({
    data,
    columns,
    enableSorting: true,
    enablePagination: true,
    pageSize: 25,
  });

  // Access table state and methods
  const { getRowModel, getHeaderGroups } = table;

  // Build custom UI with table instance
}

Hooks

useBellhopRef

A hook for managing refs to Bellhop web components with type-safe prop setting:

import { useBellhopRef } from '@actabldesign/bellhop-react';

function MyComponent() {
  const [dataGridRef, setDataGridProps] = useBellhopRef<
    HTMLBhDataGridElement,
    { columns: ColumnDef[]; data: any[] }
  >();

  useEffect(() => {
    setDataGridProps({ columns: myColumns, data: myData });
  }, [myColumns, myData, setDataGridProps]);

  return <BhDataGrid ref={dataGridRef} />;
}

Cell Renderer Helpers

Helper functions for common data grid cell rendering patterns:

import {
  cellBadge,
  cellButton,
  cellIconButton,
  cellButtonGroup,
  cellLink,
  cellAvatar,
  cellTag,
  cellTagList,
  cellToggle,
  cellCurrency,
  cellPercent,
} from '@actabldesign/bellhop-react';

const columns = [
  {
    accessorKey: 'status',
    header: 'Status',
    cell: cellBadge((value) => ({
      label: value,
      variant: value === 'Active' ? 'success' : 'neutral'
    }))
  },
  {
    accessorKey: 'price',
    header: 'Price',
    cell: cellCurrency({ currency: 'USD' })
  },
  {
    id: 'actions',
    header: '',
    cell: cellButtonGroup([
      { iconName: 'edit', onClick: (row) => handleEdit(row) },
      { iconName: 'delete', onClick: (row) => handleDelete(row) }
    ])
  }
];

See the Storybook documentation for more cell renderer patterns.

Type Exports

import type {
  // Button types
  ButtonHierarchy,
  ButtonIconPosition,
  ButtonSize,
  // Table types
  TableProps,
  TableSize,
  TableVariant,
  CellAlign,
  // DataTable types
  DataTableProps,
  ColumnDef,
  SortingState,
  ColumnFiltersState,
  RowSelectionState,
  EditMode,
  EditState,
  RowChanges,
} from '@actabldesign/bellhop-react';

Styling

Components use CSS classes from @actabldesign/bellhop-styles. Import the styles in your application:

import '@actabldesign/bellhop-styles';

Related Packages

• @actabldesign/bellhop-core - Web Components (StencilJS)
• @actabldesign/bellhop-styles - CSS styles and design tokens
• @actabldesign/bellhop-assets - SVG icons, illustrations, logos

License

MIT