Agentic Components

Production-grade component library for Shiprocket agentic interfaces. React consumers use the native React exports; Angular consumers use the packaged Custom Elements bridge.

• Repository: https://github.com/bfrs/agentic-components
• Showcase: https://agentic-components.vercel.app/
• Package: @bfrs/agentic-components

Install

Install from the public npm registry:

npm install @bfrs/agentic-components

During install, the package writes BFRS_AGENTIC_COMPONENTS.md into the consuming project. It also ensures AGENTS.md and CLAUDE.md reference that file, creating either file when missing. Existing agent files are preserved and only receive the reference line:

Use BFRS_AGENTIC_COMPONENTS.md for knowledge regarding the component library.

React Usage

import "@bfrs/agentic-components/styles";
import { BfrsProvider, Button, Card, Checkbox, Input, Text } from "@bfrs/agentic-components";

export function Example() {
  return (
    <BfrsProvider>
      <Card>
        <Text variant="title">Create shipment</Text>
        <Input placeholder="Pickup pincode" />
        <Checkbox label="Save this pickup address" defaultChecked />
        <Button onClick={() => undefined}>Continue</Button>
      </Card>
    </BfrsProvider>
  );
}

The stylesheet is safe to import globally: it does not ship Tailwind preflight, page-level resets, global font-face declarations, unprefixed utilities, or generic keyframes. React surfaces should still render inside BfrsProvider; the provider owns --bfrs-* theme variables and passes the same scope to Radix portals.

Optional: bundled SF Pro font

The main stylesheet only references the SF Pro family by name (--bfrs-font-sans) — it ships no font files, so by default you supply the font. To have the library download and apply SF Pro across your whole app, additionally import the opt-in font stylesheet once at your entry point:

import "@bfrs/agentic-components/styles";
import "@bfrs/agentic-components/fonts.css";

This bundles the SF Pro Display webfont (relative URLs, so any base path works), defines --bfrs-font-sans at the document root, and applies it to html, body. Keeping it separate means the main stylesheet stays free of global @font-face/html/body rules.

Most DOM-backed components forward compatible React props such as onClick, onKeyDown, aria-*, data-*, className, style, and refs. Controlled components expose explicit callbacks such as onValueChange, onOpenChange, onSort, onRowClick, and onPageChange.

Library-owned Tailwind utilities are prefixed with bfrs-, for example bfrs-flex, hover:bfrs-bg-primary, and bfrs-animate-shimmer. Unprefixed classes passed through className are treated as host-app classes.

Size-aware controls support sm, md, and lg. sm is the compact dashboard size for dense controls and filters.

Angular Usage

Angular apps should import the custom element registry once and include the shared stylesheet globally:

// main.ts
import "@bfrs/agentic-components/custom-elements";

/* styles.scss */
@import "@bfrs/agentic-components/styles";
/* Optional — bundled SF Pro, applied to the whole app: */
@import "@bfrs/agentic-components/fonts.css";

If Angular does not resolve the package style export, add the built CSS files in angular.json:

{
  "styles": [
    "node_modules/@bfrs/agentic-components/dist/style.css",
    "node_modules/@bfrs/agentic-components/dist/fonts.css",
    "src/styles.scss"
  ]
}

Add CUSTOM_ELEMENTS_SCHEMA to the module or standalone component that renders the tags:

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";

@Component({
  selector: "app-example",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <bfrs-input label="Pickup pincode" (value-change)="pickup = $event.detail.value"></bfrs-input>
    <bfrs-button variant="primary" (click)="continue()">Continue</bfrs-button>
  `
})
export class ExampleComponent {
  pickup = "";
  continue() {}
}

Use native Angular DOM event bindings for interactions. Do not pass React-style onClick in Angular templates:

<bfrs-button variant="primary" (click)="continue()">Continue</bfrs-button>
<bfrs-paper (click)="openDetails()">Open details</bfrs-paper>

The custom-elements entrypoint registers Angular-friendly tags for the documented component surface, including layout, forms, feedback, overlays, filters, data display, navigation, and agentic pattern components.

Use simple attributes for primitive values and [props] for structured values or callback-capable advanced props:

<bfrs-select
  placeholder="Channel"
  [props]="{ options: channelOptions, value: channel }"
  (value-change)="channel = $event.detail.value">
</bfrs-select>

<bfrs-data-table
  [props]="{ data: orders, columns: orderColumns, selection: true }"
  (cell-action)="handleTableAction($event.detail)"
  (row-click)="openOrder($event.detail.row)"
  (sort-change)="sorting = $event.detail.sorting">
</bfrs-data-table>

For DataTable action cells in Angular, use serializable column configs instead of React cell functions:

orderColumns = [
  { id: "orderId", header: "Order ID", accessorKey: "orderId" },
  {
    id: "actions",
    header: "Actions",
    cellType: "buttons",
    actions: [
      { id: "view", label: "View", variant: "outline", size: "sm", iconName: "eye" },
      { id: "ship", label: "Ship now", variant: "primary", size: "sm", disabledKey: "shipDisabled" }
    ]
  }
];

Registered tags include bfrs-box, bfrs-container, bfrs-paper, bfrs-stack, bfrs-grid, bfrs-text, bfrs-icon, bfrs-button, bfrs-icon-button, bfrs-form-field, bfrs-label, bfrs-input, bfrs-slider, bfrs-color-picker, bfrs-color-swatch-group, bfrs-textarea, bfrs-select, bfrs-date-range-picker, bfrs-searchable-select, bfrs-multi-select, bfrs-suggest-input, bfrs-option-card-group, bfrs-selectable-chip-group, bfrs-number-stepper, bfrs-file-dropzone, bfrs-reveal-field, bfrs-checkbox, bfrs-radio, bfrs-switch, bfrs-badge, bfrs-chip, bfrs-alert, bfrs-info-card, bfrs-tip, bfrs-toast-manager, bfrs-spinner, bfrs-skeleton, bfrs-empty-state, bfrs-error-state, bfrs-loading-state, bfrs-modal, bfrs-drawer, bfrs-confirm-dialog, bfrs-dropdown, bfrs-tooltip, bfrs-popover, bfrs-avatar, bfrs-metric-card, bfrs-table-pagination, bfrs-data-table, bfrs-tabs, bfrs-breadcrumbs, bfrs-action-menu, bfrs-page-header, bfrs-section-header, bfrs-layout-shell, bfrs-form-section, bfrs-filter-bar, bfrs-filter-drawer, bfrs-chat-bubble, bfrs-chat-composer, bfrs-full-page-loader, bfrs-business-info-display-card, bfrs-collapsible, bfrs-accordion, bfrs-summary-bar, bfrs-entity-display-card, bfrs-reveal-and-copy, and bfrs-step-progress-card.

Theme Overrides

The package exposes a framework-neutral theme helper for scoped token overrides. Use it from React, Angular, or plain TypeScript without importing the React component entry:

import { applyAgenticTheme } from "@bfrs/agentic-components/theme";

applyAgenticTheme({
  colors: {
    primary: "#5B45C2",
    primaryHover: "#4C35AE",
    primarySoft: "#F1ECFB",
    borderFocus: "#5B45C2"
  },
  radius: {
    control: "14px",
    card: "18px"
  },
  shadows: {
    card: "0 12px 32px rgb(91 69 194 / 0.16)"
  }
});

applyAgenticTheme() writes to an explicit target when provided, otherwise to the first mounted BFRS scope (.bfrs, [data-bfrs-root], or [data-bfrs-mount]). It never writes to the host document root. The helper accepts hex, rgb, hsl, or raw HSL channel values for semantic color tokens. Plain CSS variable overrides also work on a BFRS scope:

.bfrs {
  --bfrs-color-primary: 251 51% 52%;
  --bfrs-radius-control: 14px;
  --bfrs-shadow-card: 0 12px 32px rgb(91 69 194 / 0.16);
}

BfrsProvider also accepts theme and colorScheme="light" | "dark" props. Inline style values override generated theme variables when both are provided.

Validated Forms

Keep form validation and API checks in the app. Render field errors below inputs, then show success or failure through the toast API.

<FormField label="Pickup pincode" errorText={errors.pickupPincode}>
  <Input error={Boolean(errors.pickupPincode)} value={pickupPincode} onChange={updatePickupPincode} />
</FormField>

<bfrs-input
  label="Pickup pincode"
  [value]="pickupPincode"
  [attr.error]="errors.pickupPincode ? true : null"
  [attr.error-message]="errors.pickupPincode || null"
  (value-change)="pickupPincode = $event.detail.value">
</bfrs-input>

<bfrs-toast-manager [props]="{ toasts: toasts }" (dismiss)="dismissToast($event.detail.id)"></bfrs-toast-manager>

DateRangePicker

Use DateRangePicker for preset and custom date-range filters. Keep API date formatting in the consuming app.

import { DateRangePicker, presetToRange, type DateRangeValue } from "@bfrs/agentic-components";

const [range, setRange] = useState<DateRangeValue>({
  preset: "Last 30 days",
  ...presetToRange("Last 30 days")
});

<DateRangePicker value={range} onChange={setRange} maxRangeDays={365} />;

ToastProvider

Wrap the app once and call toast helpers from app event handlers.

import { Button, ToastProvider, useToast } from "@bfrs/agentic-components";

function SaveButton() {
  const { success, danger } = useToast();

  return <Button onClick={() => success("Changes saved")}>Save</Button>;
}

<ToastProvider>
  <SaveButton />
</ToastProvider>;

Checkbox

Use Checkbox for independent true/false decisions or multi-select choices. It renders as a square checklist control, while Radio renders circular options for single-choice groups.

import { Checkbox } from "@bfrs/agentic-components";

<Checkbox
  label="Accept terms"
  description="Use checkboxes when each option can be selected independently."
  checked={accepted}
  onCheckedChange={setAccepted}
/>

<Checkbox label="Partially selected" checked="indeterminate" />

Development

npm run typecheck
npm run lint
npm run build:lib
npm run build:demo

npm run build:lib outputs the package to dist.

npm run build:demo outputs the showcase app to dist-demo.

Publishing

Package publishing is configured for npmjs public packages. Publish only through the controlled release flow:

npm run changeset
npm run version-packages
git tag v0.1.0
git push origin main --tags

The Publish Package GitHub Action publishes to npmjs on version tags, published GitHub releases, or manual workflow dispatch. Configure the repository secret NPM_TOKEN with publish access.

Showcase Deployment

The public documentation is hosted at https://agentic-components.vercel.app/.

The showcase build target is dist-demo:

npm run build:demo