hs-uix components

The model

A collection component owns the chrome, you own the data

Every component in this guide takes the same shape: an array of rows and a description of how to display them. None of them fetch. data in, JSX out.

That split is deliberate, and it is the thing to internalise before reading the rest of this page. Fetching inside a UI extension means runServerless against your card backend, which means auth, the sandbox, and a request budget — all of which belong to your Worker, not to a table. So DataTable, Kanban, Feed, and Calendar all take data (or items / events) plus loading and error, and never a fetch prop. If you are looking for one, you want the CRM-connected components at the end of this guide.

What the component does own is everything between the raw array and the pixels: search, filters, sort, pagination, selection and bulk actions, grouping, empty and loading and error states, and i18n through a labels prop. That is the reason to reach for one instead of mapping over an array yourself — not the markup, which is easy, but the twenty pieces of state around it, which are not.

The subpaths are separate entry points, so you only pay for what you import:

import { DataTable } from 'hs-uix/datatable';
import { Kanban } from 'hs-uix/kanban';
import { FormBuilder } from 'hs-uix/form';
import { Feed } from 'hs-uix/feed';
import { Calendar } from 'hs-uix/calendar';
import { FilterBuilder } from 'hs-uix/filter';
import { KeyValueList, SectionHeader } from 'hs-uix/common-components';
import { formatCurrency } from 'hs-uix/utils';

Bundle size is a real constraint inside HubSpot's sandbox, so import from the subpath rather than the package root. See the performance budget section of the UI extensions guide for the limits.

01/ 06

Pick the component that matches the shape of your data

The choice is almost always decided by one question: what is the primary axis your user reads along?

Two of these overlap more than the table suggests, and it is worth being explicit about it. DataTable and Kanban are the same data with different axes — the same deal list is a table when you want to compare amounts and a board when you want to move things through a pipeline. They are close enough that hs-uix/utils ships deriveCardFieldsFromColumns, which projects a DataTable columns config into Kanban cardFields in one call, so offering both views of one collection is not two configs to maintain:

import { deriveCardFieldsFromColumns } from 'hs-uix/utils';
 
const CARD_FIELDS = deriveCardFieldsFromColumns(COLUMNS, { titleField: 'name' });

Similarly, Feed and Calendar are both time, but a feed is when it happened and a calendar is how long it takes and what it collides with. If your records have no end time, you want a feed.

02/ 06

Render a collection with DataTable

DataTable is the workhorse, and it has by far the largest surface — around seventy props. You will use six of them.

import { DataTable } from 'hs-uix/datatable';
import { formatCurrency } from 'hs-uix/utils';
 
<DataTable
  data={deals}
  loading={loading}
  error={error}
  columns={[
    { id: 'name', label: 'Deal', sortable: true },
    { id: 'amount', label: 'Amount', render: (v) => formatCurrency(v) },
    { id: 'stage', label: 'Stage' },
  ]}
  searchFields={['name']}
  pageSize={25}
/>

That is the whole basic case. Everything below is the reason to use it over a hand-rolled table.

Selection and bulk actions

selectable turns on checkboxes and a selection bar. selectionActions are the buttons that appear in it. The prop worth knowing about is onSelectAllRequest: when a user ticks "select all" on a server-paginated table they mean all matching rows, not the 25 on screen, and this callback hands you the current search and filter state so you can act on the real set rather than the visible page.

<DataTable
  selectable
  rowIdField="id"
  selectionActions={[{ label: 'Change owner', onClick: (ids) => reassign(ids) }]}
  onSelectAllRequest={(payload) => reassignMatching(payload)}
  recordLabel={{ singular: 'deal', plural: 'deals' }}
/>

Inline editing

editMode puts a row into an editable state and onRowEdit receives the result. This is the difference between a report and a tool — a rep can fix an amount without leaving the record.

Grouping

groupBy buckets rows under collapsible headers. Grouping deals by stage inside a table is often the right answer when a board would be too much furniture for four records.

Server-side mode

Set serverSide and the component stops filtering and paging in the browser; onParamsChange then fires with the full { search, filters, sort, page } state and you re-fetch. Use it once your collection outgrows what is sensible to ship to the iframe in one response.

Empty, loading, and error states

emptyTitle / emptyMessage cover the common case; renderEmptyState, renderLoadingState, and renderErrorState take over entirely when you need something bespoke. Do fill these in. An empty table with no explanation is the most common way a good card feels broken.

03/ 06

Turn the same collection into a board with Kanban

Kanban takes the same rows and swaps the axis for a stage. What it adds over a table is the stage model itself.

import { Kanban } from 'hs-uix/kanban';
import { formatCurrency } from 'hs-uix/utils';
 
const STAGES = [
  { value: 'discovery', label: 'Discovery' },
  { value: 'proposal', label: 'Proposal sent', wipLimit: 3, variant: 'warning' },
  { value: 'negotiation', label: 'Negotiation' },
  { value: 'closedwon', label: 'Closed won', variant: 'success', terminal: true },
];
 
<Kanban
  data={deals}
  stages={STAGES}
  groupBy="stage"
  cardFields={[
    { field: 'name', placement: 'title' },
    { field: 'amount', placement: 'meta', render: (v) => formatCurrency(v) },
    { field: 'owner', placement: 'footer' },
  ]}
  onStageChange={(row, newStage, oldStage) => advance(row.id, newStage)}
/>

cardFields is the whole card design

Each field declares a placement — title, subtitle, meta, body, or footer — and optionally a render, an href, truncate, and a visible predicate. There is no card template to write; you are describing where values land.

WIP limits are a signal, not a gate

Set wipLimit on a stage and the header renders count / limit with an "Over WIP" tag once exceeded. onWipExceeded fires once per crossing, including on a board that mounts already over the limit — not on every render.

Read the rest of that behaviour carefully before you build on it: an over-limit transition still completes. The server is the source of truth, and the board will not block a drag. If you need a hard gate, enforce it in the handler behind onStageChange and let the rejection come back, rather than expecting the component to refuse.

Stage transition prompts

A stage can require input before a card enters it — declared per stage via stage.onEnterRequired.render, which lets you capture a close reason or a lost-to competitor before the move commits. onStageChange then receives that result as its fourth argument.

Swimlanes

swimlaneBy groups the board vertically as well as horizontally — deals by stage across, by owner down. With metricsPerLane the metrics panel renders inside each lane instead of globally. This is the point at which a board stops being a prettier list and starts being a management view.

Per-stage pagination

stageMeta plus onLoadMore lets each column paginate independently, so you can mix client-side columns and server-loaded ones on the same board.

04/ 06

Build a form from your portal’s own properties

FormBuilder takes a fields array and handles validation, layout, and submission. The reason to use it inside a HubSpot extension specifically is fieldsFromHubSpotProperties.

import { FormBuilder, fieldsFromHubSpotProperties } from 'hs-uix/form';
 
const fields = fieldsFromHubSpotProperties(properties);
 
<FormBuilder fields={fields} onSubmit={(values) => save(values)} />

Hand it the property definitions your portal returns and it produces the matching field set — an enumeration property becomes a select with its real options, a date property becomes a date field, a currency property becomes a currency field. You are not restating your portal's schema in a second place where it can drift.

The field types available are text, password, textarea, number, stepper, currency, date, time, datetime, select, multiselect, toggle, checkbox, checkboxGroup, radioGroup, display, slot, repeater, and fieldGroup.

Beyond that, four features carry most forms:

• steps — a multi-step form with an indicator, and validateStepOnNext so a user cannot advance past an invalid step.
• dependsOn on a field — conditional visibility, so a "lost reason" appears only when the stage is closed-lost.
• repeater — a repeating group, for line items or contacts.
• useFormPrefill(properties, mapping) — a hook that maps a record's existing properties onto initial values, so an edit form opens populated.

confirmDiscard is worth turning on for anything longer than three fields. Inside a CRM record a user's attention leaves often, and losing a half-filled form to a stray click is a bad way to learn that.

05/ 06

Compose a filter that runs as a CRM search

FilterBuilder is the odd one out here: it does not render your data, it renders a query. The user composes nested AND/OR conditions, and you get back a filter tree.

import { FilterBuilder, toCrmSearchFilterGroups } from 'hs-uix/filter';
 
<FilterBuilder
  properties={[
    { name: 'dealstage', label: 'Stage', type: 'enumeration', options: stageOptions },
    { name: 'amount', label: 'Amount', type: 'number' },
    { name: 'closedate', label: 'Close date', type: 'date' },
  ]}
  value={tree}
  onChange={setTree}
/>

The payoff is the second import. toCrmSearchFilterGroups(tree) compiles that tree into the filterGroups shape HubSpot's CRM search API expects, so the thing your user built in the UI goes straight to the API with no translation layer of your own:

const filterGroups = toCrmSearchFilterGroups(tree);
await runServerless({ name: 'searchDeals', parameters: { filterGroups } });

validateTree returns the errors before you send it, and countConditions is useful for a "3 filters applied" badge. maxDepth caps how deeply a user can nest groups — worth setting, because a filter nobody can read is a support ticket.

06/ 06

Skip the fetch with the CRM-connected components

Everything above assumes you fetch. For the specific and very common case of "show me records from this portal", hs-uix/utils ships two components that close that loop for you:

import { CrmDataTable, CrmKanban } from 'hs-uix/utils';
 
<CrmDataTable
  objectType="deals"
  properties={['dealname', 'amount', 'dealstage', 'closedate']}
  columns={COLUMNS}
  serverSide
/>
 
<CrmKanban objectType="deals" groupBy="dealstage" cardFields={CARD_FIELDS} />

These take an objectType and a property list and handle the CRM search themselves — including pagination, the search and filter parameter mapping, and normalising HubSpot's { id, properties: { … } } response shape into flat rows. CrmKanban will even derive its stages from the returned batch when you do not pass stages, though you should pass them for real pipeline labels rather than raw internal values.

If you want that data handling without their rendering, the same machinery is exposed as hooks:

• useCrmSearchDataSource(params, options) — returns { data, pagination, hasMore, loading, error, totalCount }.
• useCrmSearchOptions(params, options) — the same, shaped as { label, value } options for a select.
• buildCrmSearchConfig / normalizeCrmSearchRows — the two halves on their own, if you are driving the request yourself.

One caveat to size up before adopting these: they move the CRM query into the extension. That is exactly what you want for a read-only view of standard objects, and exactly what you do not want when the query needs a secret, a third-party call, or business logic you would rather not ship into an iframe. Those still belong in a card backend on your Worker.

Reference

The smaller pieces

hs-uix/common-components holds the parts that show up inside the collections above, and are worth knowing individually:

• KeyValueList and SectionHeader — the two you will use most; a labelled property list and a section rule.
• CrmRecordPicker and CrmLookupSelect — record association pickers, so "attach this to a company" is not a text field.
• DateRangePicker, CollectionToolbar, ActiveFilterChips, CollectionCount, CollectionSortSelect, CollectionFilterControl — the toolbar furniture the collections assemble internally, exposed so a custom view can match.
• AvatarStack, AutoTag, AutoStatusTag, Icon, Spinner, StyledText.

hs-uix/utils holds the formatters and the glue: formatCurrency, formatCurrencyCompact, formatDate, formatDateTime, formatPercentage, buildOptions, sumBy, deriveCardFieldsFromColumns, and the filter helpers (filterRows, searchRows, buildActiveFilterChips).

Use the formatters rather than Intl directly. They accept the value shapes HubSpot actually returns — including its date objects — so formatDate on a HubSpot date property does the right thing without a conversion step.