noviq-ui
v4.8.1
Published
Lightweight React component library — forms, data tables, drawers, and modals — for the Noviq product suite.
Maintainers
Readme
noviq-ui
A lightweight React UI component library built with React and bundled using Vite. It provides reusable UI components that can be shared across multiple projects.
Keywords: react components, ui library, component library, design system, typescript, form components, data table, react table, drawer, modal, dropdown, admin dashboard, date picker, time picker, month picker, i18n, locale, translation, localization, currency formatting, client-side search.
Installation
Install noviq-ui with npm
npm install noviq-uiImport the stylesheet once, near the root of your app:
import "noviq-ui/style.css";Breaking change in 2.0.0
Input's onChange now receives the raw value, not the DOM event:
- <Input type="text" value={name} onChange={(e) => setName(e.target.value)} />
+ <Input type="text" value={name} onChange={setName} />This applies to every field type — onChange(value: any) => void. The value's shape depends on
the field (string for text-like fields, boolean for checkbox/radio/switch, File for file,
File[] for multipleFile, an option object for select, an array of option objects for
multiSelect).
Breaking change in 3.0.0
Table's apiFunction used to have to resolve to exactly { result: T[], totalCount: number }
— that shape mirrored one specific consumer's backend rather than being a neutral contract.
apiFunction now resolves to your backend's raw, untouched response instead. Every app using
apiFunction must wrap its root (or the relevant subtree) in NoviqUIConfigProvider, declaring
once how to read rows/total out of that raw response — see the Table section below.
TableQueryResult is removed from the public API; TableQueryParams is now
Record<string, unknown> since its field names are configurable
(config.table.requestParams) rather than fixed.
preFetchedData-only tables are unaffected — no NoviqUIConfigProvider is required for them.
Breaking change in 4.0.0
noviq-ui no longer depends on formik or react-hot-toast. Which form-state and notification
libraries an app uses is the app's call, but both were being installed into every app that
depended on noviq-ui.
formikis no longer installed with noviq-ui.<Form />never needed it at runtime — it is typed against a smallFormControllershape (values,errors,touched,setFieldValue), which auseFormik()instance satisfies as-is. If your app imports from"formik", add it to yourpackage.json; nothing else changes.react-hot-toastis no longer installed, and<Table />no longer shows its own toasts. Export outcome is reported through the newnotifyoption onNoviqUIConfigProvider— see "Export" below. Without it the table stays silent (the "Exporting…" button state still shows, and a failure is stillconsole.errored), and you no longer need to mount a<Toaster />for noviq-ui's sake.
<NoviqUIConfigProvider
config={{
table: { responseFormat: { rowsPath: "result", totalPath: "totalCount" } },
+ notify: (message, kind) => (kind === "error" ? toast.error(message) : toast.success(message)),
}}
>What changed in 4.8.1
All additive: with nothing configured, a status column looks exactly as it did.
statuscells are configurable — your own statuses, their colour classes and labels, a fallback, or arenderfor the whole pill — onNoviqUIConfigProvider(statuses), on a<Table statuses>and on a single column (column.statuses). See "Status cells".- The pill's colours are custom properties you can override:
--nq-status-success-bg,-text,-border, and the same fordanger,warning,infoanddefault(see "Theming"). No colour is written into the component's CSS any more. - Fixed: your own status class could lose. A status pill was an outline
Badge, and a class of yours has the same specificity as that variant — so it won or lost depending on which stylesheet loaded first (the built-in tones only won through!important). The pill is now a plainnq-badgewith just the status class, and the tone classes no longer use!important. Status pills no longer carry thenq-badge-outlineclass; how they look is unchanged. Table'sstatusVariantMapstill works;statuses.stylessupersedes it.
What changed in 4.8.0
Five fixes to things that looked supported and weren't. All additive; nothing that worked changes.
- Filters work on a
preFetchedDatatable. The Filters drawer and its chips used to appear and do nothing to the rows (they only built a payload for anapiFunction). The table now filters the rows itself — see "Filters". With anapiFunctionnothing changes: your server filters. - AM and PM are translatable. Two new text keys,
timeAmandtimePm(default"AM"/"PM"), are what theA/aformat tokens print — in table cells, filter chips and exports, and in theTimePicker's AM/PM column. A Spanish app sets"a. m."/"p. m.". The value the picker hands back is still 24-hourHH:mm. A dictionary you typed asRecord<TextKey, TextValue>will ask for the two new keys, as intended. - Excel export sizes each column to its content. A column was only as wide as its heading, so a long cell (a shift window, an address) was cut off when the file opened. Columns are now as wide as their widest cell, between 10 and 60 characters. The header's white text colour is also written the way the file format specifies.
- The filter drawer's controls have accessible names. A text, date or month filter's input is
named by the filter's
label, and each option's checkbox by the option, so a screen reader — orgetByRole("checkbox", { name: "Engineering" })in your tests — can find them. Only the section titles had text before, and nothing tied it to the control. - A closed
Drawerno longer casts a shadow onto the page. A closed drawer waits just off the edge of the screen, and its drop shadow reaches back past that edge, so every page with a mounted-but-closed drawer had a faint dark strip down one side (darker with several). The shadow now appears with the slide.
What changed in 4.7.0
A real-browser pass over every popup inside every overlay, plus an audit of everything noviq-ui puts in the page's CSS namespace. Two things you might notice:
- Custom properties are renamed:
--primary→--nq-primary,--radius→--nq-radius, … (18 tokens). Classes were alreadynq-*(4.6.0). Before, noviq-ui defined--primary,--radius,--shadow… on:root— names an app's own CSS commonly uses, so one overwrote the other. Now nothing noviq-ui ships can collide with your CSS. If you themed by overriding the old names, either rename your overrides (table in "Theming") or, to change nothing else, addimport "noviq-ui/legacy-tokens.css"afternoviq-ui/style.css. lucide-reactis no longer a dependency. It stamped the global classeslucideandlucide-<name>on every icon, which your CSS (or your own use of lucide) could match. The icons are the same shapes, drawn by noviq-ui without any class.Modalis portaled to<body>(the docs always said it was; it rendered in place). Under a host wrapper withtransform,filterorz-indexit could be offset from the viewport or sit under your own header.- Stacking fixes (see "Stacking and z-index"): a Modal opened from a Drawer used to render
behind it; the reject popover was hidden behind any Modal or Drawer; a
FullPageSection's sticky footer was painted under a table's pinned columns.
What changed in 4.6.0
All additive: nothing that worked changes, and each new behaviour is opt-in or fixes something that was plainly wrong.
<Table serverSort>— sort on the server. See "Sorting" below.- A filter chip reopens the filters drawer when clicked.
FilterChipsgetsonChipClick,FilterDrawergets optionalopen/onOpenChange. - Pinned columns are measured. A pinned column used to be offset by the declared
width(140px when unset) of the pinned columns before it, so any column that rendered at another width left a gap or an overlap. The header cells are now measured after layout and on resize; a column that can't be measured falls back to its declared width. <Drawer unmountOnClose>— a closed drawer no longer has to keep a live form behind it. Default unchanged. The Table's own two drawers use it.<NoviqUIConfigProvider inherit>— a nested provider laid over its parent's config instead of replacing it. Default unchanged.- Accessibility: a sortable header has
aria-sort, is a tab stop and sorts on Enter / Space; the select-all and row checkboxes have names ("Select all rows", "Select row" — text keystableSelectAll,tableSelectRow);Checkboxacceptsaria-label. - Fixed: the search box's debounce reset a table to page 1 half a second after it mounted, even though the search hadn't changed.
- New text keys (
tableSelectAll,tableSelectRow): a dictionary typedRecord<TextKey, TextValue>will ask for them, as intended.
What changed in 4.5.0
config.text: every label, placeholder and message the library shows can be replaced — one key at a time, inNoviqUIConfigProvider. 96 keys, all defaulting to the English you see today, so nothing changes until an app sets one. See "Text and translation" below.- Two accessible names that were missing (they read as unnamed buttons to a screen reader):
the pager's four arrows ("First page" … "Last page") and the
Drawer's close button ("Close"). Both are text keys. - No default changed in this release. An unconfigured app renders exactly what 4.4.0 did, apart
from the two new
aria-labels.
What changed in 4.4.0
New, and one default that changed:
- Default change —
TimePickeris a 12-hour clock when the app sets noformats.time. It used to be 24-hour while every Table cell showedhh:mm A; now both follow the library defaulthh:mm A, so a picker and a cell show a time the same way.value/onChangeare still 24-hour"HH:mm". To keep the old 24-hour picker: setformats.time: "HH:mm"(the Table follows too) or passhourCycle={24}to that picker. An explicithourCyclealways wins, andhourCycle={12}with no configured format still lists00 … 11. TablewithpreFetchedDatanow searches and pages client-side. The search box used to do nothing and the pager said "Showing 1 to 10 of 25" over all 25 rows. Now the term filters the rows by the text the visible columns show, and one page renders when the pager is shown;isPaginationHiddenstill shows every row. Select-all picks the rows on the page; export writes every searched row. If you fed the table one already-paged slice and kept the pager visible, passisPaginationHidden— otherwise it pages your slice again.formats.locale,formats.currency,formats.weekStart— see "Regional settings" below.column.cell(row, text, rawRow, rawValue)— a 4th argument: the accessor's untouched value (number, boolean,null, array), next to the trimmed text.<Input type="search" />renderslabel,required,helper,error,disabledandmaxLength; it ignored all of them. A bare search field is unchanged.
Constants
Every fixed value the components accept has a named constant, so your code doesn't repeat stringly-typed literals:
import { Button, Drawer, BUTTON_VARIANT, BUTTON_SIZE, BUTTON_TYPE, DRAWER_SIDE } from "noviq-ui";
<Button variant={BUTTON_VARIANT.OUTLINE} size={BUTTON_SIZE.SM} type={BUTTON_TYPE.SUBMIT}>Save</Button>
<Drawer isOpen={open} onClose={close} side={DRAWER_SIDE.LEFT} />The constants hold the same strings the props have always accepted, so plain literals
(variant="outline") keep working and nothing needs migrating. Each group also has a derived
type (ButtonVariant, DrawerSide, …).
| Constant | Used by |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| INPUT_TYPE, FORM_FIELD_TYPE, COL_SPAN | Input / Form field types (incl. DATE_PICKER, TIME_PICKER, MONTH_PICKER) and colSpan |
| BUTTON_VARIANT, BUTTON_SIZE, BUTTON_TYPE | Button (BUTTON_TYPE is the native type attribute) |
| BADGE_VARIANT | Badge |
| DRAWER_SIDE, DRAWER_SIZE, MODAL_SIZE | Drawer, Modal |
| HOUR_CYCLE, TIME_PERIOD | TimePicker |
| CELL_TYPE, FILTER_TYPE | Table column type, filterConfigs |
| SORT_DIRECTION, STICKY_POSITION, COLUMN_ALIGN | Table columns |
| TABLE_COLUMN_ID | ids of the auto-injected select / actions columns |
| ACTION_ID | Table toolbar actions (ACTION_ID.ADD is the primary action) |
| ROW_ACTION_TYPE, ROW_ACTION_VARIANT, BULK_ACTION_VARIANT | rowActions, bulkActions |
| NOTIFY_KIND | the kind passed to config.notify |
| NO_TEXT_PLACEHOLDER | what an empty table cell shows |
Usage/Examples
import { useState } from "react";
import { Input, Button, Drawer, Modal } from "noviq-ui";
function App() {
const [name, setName] = useState("");
return (
<div>
<Input type="text" label="Name" value={name} onChange={setName} />
<Button variant="default">Save</Button>
</div>
);
}
export default App;Drawer
import { useState } from "react";
import { Drawer, Button } from "noviq-ui";
function Example() {
const [open, setOpen] = useState(false);
return (
<>
<Button onClick={() => setOpen(true)}>Open Drawer</Button>
<Drawer
isOpen={open}
onClose={() => setOpen(false)}
title="Edit item"
side="right"
size="md"
closeOnOutside
footer={<Button onClick={() => setOpen(false)}>Save</Button>}
>
Drawer content goes here.
</Drawer>
</>
);
}Modal
import { useState } from "react";
import { Modal, Button } from "noviq-ui";
function Example() {
const [open, setOpen] = useState(false);
return (
<>
<Button onClick={() => setOpen(true)}>Open Modal</Button>
<Modal
isOpen={open}
onClose={() => setOpen(false)}
title="Confirm"
closeOnOutside
footer={<Button onClick={() => setOpen(false)}>Confirm</Button>}
>
Modal content goes here.
</Modal>
</>
);
}Closed drawers. By default a closed Drawer keeps its children mounted, just hidden — handy
for state that should survive, but a form inside stays live (effects, autofocus) and two drawers can
render the same id. <Drawer unmountOnClose> mounts them when it opens and removes them once it
has slid away, so each open starts fresh.
Escape closes only the topmost layer. With a date/time/month picker, a select's menu or a
DropdownMenu open inside a Modal or Drawer, the first Escape closes that picker or menu and the second closes
the overlay. A Drawer opened from a Modal closes before the Modal does, and an open Drawer
without closeOnOutside ignores Escape but still shields the Modal beneath it. (A Modal
always closes on Escape; a Drawer only with closeOnOutside.)
Form + Formik
Form renders a config-driven list of Inputs wired to a Formik instance
(or anything with the same small shape — see below). Formik is not a dependency of noviq-ui;
install it yourself if you use it.
import { useFormik } from "formik";
import { Form, FormFooter } from "noviq-ui";
function Example() {
const formik = useFormik({
initialValues: { firstName: "", lastName: "" },
validate: (values) => {
const errors = {};
if (!values.firstName) errors.firstName = "Required";
return errors;
},
onSubmit: (values) => console.log(values),
});
const fields = [
{
inputKey: "firstName",
type: "text",
label: "First name",
required: true,
colSpan: 2,
},
{ inputKey: "lastName", type: "text", label: "Last name", colSpan: 2 },
];
return (
<form onSubmit={formik.handleSubmit}>
<Form inputList={fields} formik={formik} />
<FormFooter onCancel={formik.resetForm} onSubmit={formik.submitForm} />
</form>
);
}The formik prop only needs { values, errors?, touched?, setFieldValue(key, value) } (exported
as the FormController type), so Form works just as well with any other form state — an error
is shown for a field only once its key is also truthy in touched.
colSpan is how many fields share a row, not "columns spanned out of 3" — 1 = alone
(100% width), 2 = one of two side by side (50% each), 3 = one of three side by side (~33%
each). Fields meant to sit on the same row need the same colSpan value (as firstName/
lastName do above); a 2 next to a 1 won't fill the row evenly, they'll just wrap.
TimePicker
A time field with scrollable hour/minute columns — a consistent alternative to the browser's
native <input type="time">, whose look and 12/24-hour behavior vary by browser and OS locale.
Works as a 12-hour clock with an AM/PM column (the default, hh:mm A, as in Table cells) or a
24-hour clock — set formats.time: "HH:mm" once, or hourCycle={24} per picker.
import { useState } from "react";
import { TimePicker } from "noviq-ui";
function Example() {
const [start, setStart] = useState("14:30");
return (
<>
<TimePicker value={start} onChange={setStart} /> {/* 02:30 PM */}
<TimePicker
value={start}
onChange={setStart}
hourCycle={24}
minuteStep={15}
/>{" "}
{/* 14:30 */}
</>
);
}value/onChangeare always 24-hour"HH:mm"strings —hourCycle={12}only changes how the time is shown and picked, so the value you store and send to a backend doesn't depend on the display mode. Clearing callsonChange(""). An empty (or unparseable) value shows the placeholder — never a misleading00:00. A value with seconds ("09:30:45") is accepted and displayed without them; the picker emitsHH:mmonly.hourCycle: left unset, the clock followsformats.time—hh:mm Aby default, a 12-hour clock listing12, 01 … 11with an AM/PM column.24lists hours 00–23.12is the same AM/PM clock; with no configuredformats.timeit lists hours 00 … 11 — the zero-based 12-hour clock (Intl'sh11), where00 AMis midnight and00 PMis noon (stored as00:xxand12:xx) — and with anhhpattern configured it lists12, 01 … 11. Picking an hour keeps the current AM/PM; picking AM/PM keeps the hour and minute.- The minute column lists every minute, 00–59, in both clocks.
minuteStepmakes it coarser (minuteStep={15}→ 00, 15, 30, 45). A value that isn't on the grid ("09:32"with a step of 5) is still displayed as-is. - Opens on click, or
ArrowDown/ArrowUp/Enter/Spacefrom the keyboard — not on bare focus, so tabbing through a form doesn't pop pickers open. Inside:ArrowUp/ArrowDownmove within a column,ArrowLeft/ArrowRightswitch column, andEntercommits the highlighted option and moves on to the next column — hour, then minute, then (12-hour only) AM/PM, closing after the last.Escape/Tabclose without changing the value. - Props:
value,onChange,hourCycle,minuteStep,placeholder,disabled,error,clearable(defaulttrue),id,name,className,aria-label. - Selecting an hour on an empty field starts the minute at
00(a minute first starts the hour at00; AM/PM first on an empty field gives00:00for AM and12:00— noon, shown00:00 PM— for PM). - Also available as a form field:
<Input type="timePicker" hourCycle={12} minuteStep={15} />(and inForm'sinputList).<Input type="time" />is unchanged and still the native input.
DatePicker
A calendar dropdown for a single date — month/year selects, a Today button, min/max limits and full keyboard support, with no extra dependency.
import { useState } from "react";
import { DatePicker } from "noviq-ui";
function Example() {
const [joined, setJoined] = useState("2024-03-05");
return (
<DatePicker
value={joined}
onChange={setJoined}
minDate="2020-01-01"
maxDate="2030-12-31"
/>
);
}value/onChange/minDate/maxDateare"YYYY-MM-DD"strings (a trailing time such as"2024-03-05 09:30"is accepted and ignored). Clearing callsonChange(""). The field displaysDD/MM/YYYY. A value that isn't a real calendar date ("2023-02-30") shows the placeholder.- Dates are handled as plain year/month/day — never through
new Date("YYYY-MM-DD"), which reads as UTC and shifts the day in some time zones. minDate/maxDateare inclusive. Days outside them are disabled and can't be picked, month arrows stop at the bounds, and the month/year selects only offer what's allowed. With no bounds the year select spans 1900 to 100 years from now.- Days from the neighbouring months are shown (always six weeks, so the height never jumps) and can be picked.
- Keyboard: opens on click or
ArrowDown/ArrowUp/Enter/Space(not on bare focus). Inside: arrows move by day/week,PageUp/PageDownby month (Shiftfor year, clamping 31 Jan → 29 Feb),Home/Endto the week's start/end,Enter/Spacechooses,Escape/Tabclose. - Props:
value,onChange,minDate,maxDate,placeholder,disabled,error,clearable(defaulttrue),id,name,className,aria-label. - Form field:
<Input type="datePicker" minDate=... maxDate=... />.<Input type="date" />is unchanged and still the native input.
MonthPicker
A month-and-year grid, for fields like a billing period.
import { MonthPicker } from "noviq-ui";
<MonthPicker
value="2024-03"
onChange={setPeriod}
minMonth="2023-01"
maxMonth="2024-12"
/>;value/onChangeare"YYYY-MM";minMonth/maxMonthtake"YYYY-MM"(or a full"YYYY-MM-DD", whose day is ignored). The field displaysMM/YYYY.- Year arrows step the shown year; months outside the bounds are disabled. Keyboard: arrows move by
month (
Up/Downby row of three),PageUp/PageDownby year,Home/Endto January/December. - Props:
value,onChange,minMonth,maxMonth,placeholder,disabled,error,clearable,id,name,className,aria-label. - Form field:
<Input type="monthPicker" minDate=... maxDate=... />(the sameminDate/maxDateprops as the other date fields).<Input type="month" />is unchanged.
FullPageSection
A full-page layout for a single-step form that has too many fields for a Drawer or Modal: a
back arrow with the title (and optional subtitle), the form inside a card, and a sticky footer.
import { FullPageSection, Form } from "noviq-ui";
function AddLocationPage() {
return (
<FullPageSection
title="Add location"
subtitle="Where your people work"
onBack={() => navigate("/locations")}
onSubmit={formik.submitForm}
loading={formik.isSubmitting}
>
<Form inputList={fields} formik={formik} />
</FullPageSection>
);
}- No router dependency.
onBackdoes the navigating; without one the back arrow callswindow.history.back(). Cancel callsonCancel, falling back toonBack. - The default footer is Cancel + Submit (
cancelLabel,submitLabel).loadingdisables both and showsloadingLabel("Saving...") on the submit button. Passfooterto replace it entirely. - It's a single-step layout, not a multi-step wizard.
Table
Table needs to know your backend's response shape once, via NoviqUIConfigProvider wrapped
around your app root (or wrapped more locally, if different screens hit different backends):
import { NoviqUIConfigProvider, Table } from "noviq-ui";
// apiFunction receives { ...apiParams, search, page_no, rows_per_page } (the key names are
// customizable via config.table.requestParams) and should resolve to your backend's raw,
// untouched response — Table reads rows/total out of it using config.table.responseFormat.
function App() {
return (
<NoviqUIConfigProvider
config={{
table: {
// For a backend returning { result: { result: [...], totalCount: 42 } }:
responseFormat: {
rowsPath: "result.result",
totalPath: "result.totalCount",
},
},
}}
>
<Example />
</NoviqUIConfigProvider>
);
}
function Example() {
const columns = [
{ id: "name", heading: "Name", accessorKey: "name", sortable: true },
{ id: "status", heading: "Status", accessorKey: "status", type: "status" },
{
id: "joinDate",
heading: "Joined",
accessorKey: "joinDate",
type: "date",
},
];
const fetchEmployees = (params) =>
fetch(`/api/employees?${new URLSearchParams(params)}`).then((r) =>
r.json()
);
return (
<Table
columns={columns}
apiFunction={fetchEmployees}
searchPlaceholder="Search..."
/>
);
}NoviqUIConfigProvider is mandatory for any Table using apiFunction — rendering one without
either a Provider ancestor or a per-instance responseFormat prop throws immediately with an
actionable error message. For a response shape a dot-path can't express, use a getRows/
getTotal function pair instead of rowsPath/totalPath — they're only ever called with a
response that has actually arrived (never undefined while loading), so they don't need to
null-guard. A specific <Table> can override the app-wide format with its own responseFormat
prop — e.g. one screen calling a third-party API with a different shape than the rest of the app.
Pass preFetchedData instead of apiFunction for a fully client-controlled table (no fetching,
no @tanstack/react-query, and no NoviqUIConfigProvider requirement — you own the array).
While your own request is still in flight, pass isPrefetchedDataLoading — the table shows its
loading state (not "No data found") even though the array is still empty.
With preFetchedData the table does the searching and paging itself: the search box filters the
rows by the text the visible columns show (a date as it is displayed, a status as its label; the
- placeholder for an empty cell never matches), and the pager renders one page of the searched,
sorted rows. Pass isPaginationHidden to show every row — do that if you pass one already-paged
slice. With an apiFunction the term is sent to your backend instead and the rows that come back
are shown as they are.
A custom cell render function is cell(row, cellValue, rawRow, rawValue): cellValue is the
accessor's value as trimmed text ("-" when empty), rawValue the same value untouched — a number,
boolean, null or array. It is undefined for a column with no accessorKey.
Sorting
By default a click on a sortable header reorders the rows the table already has — for an
apiFunction table that is only the current page. Add serverSort and the server does it:
<Table
columns={[
{ id: "name", heading: "Name", accessorKey: "name", sortable: true },
{
id: "owner",
heading: "Owner",
accessorKey: "owner",
sortable: true,
sortKey: "owner_name",
},
]}
apiFunction={fetchEmployees}
serverSort
/>- A click sends
sort_byandsort_order("asc"/"desc") with the request —sort_byis the column'ssortKey, else itsaccessorKey, else itsid— and shows the rows exactly as they come back. A third click clears it; no sort params are sent until a column is sorted. - The page goes back to 1 when the sort changes, and an export is requested in the same order as the screen.
- Rename the params with
config.table.requestParams.sortBy/.sortDirection, like the others. - With
preFetchedDatathe prop is ignored: those rows are always sorted in the table. - Sortable headers are keyboard-operable either way (Tab to one, Enter or Space) and report
aria-sort.
Column management
Pass a stable id to enable the "Columns" chooser (hide/show, drag-to-reorder, pin left/right)
and persist those settings to localStorage:
<Table id="employees-table" columns={columns} apiFunction={fetchEmployees} />Without id, column customization still works but is in-memory only (resets on remount).
localStorage key: noviq-ui-table-columns:${id} — plain string, so a multi-tenant or
multi-user app that wants isolated settings per tenant/user should build that into id itself,
e.g. id={employees-${tenantId}}. Set isColumnSettingHidden to hide the chooser entirely.
Column-level visible/sticky in a column definition set the default before any user
customization (or persisted settings) apply.
A pinned column is placed after the measured width of the pinned columns before it, so you don't
need to give pinned columns a width for them to line up (the table measures again when it
resizes). A width is only the fallback for a column that can't be measured yet.
Row selection, row actions, bulk actions
Pass getRowId to enable a checkbox column (auto-injected, sticky-left) and pass rowActions to
enable an actions column (auto-injected, sticky-right) — you never declare these in columns
yourself:
<Table
columns={columns}
apiFunction={fetchEmployees}
getRowId={(row) => row.id}
onRowSelectionChange={(selectedIds) => console.log(selectedIds)}
rowActions={(row) => [
{ label: "View", type: "button", onClick: ({ row }) => openDetails(row) },
{
label: "Reject",
variant: "reject",
onConfirm: ({ row, reason }) => rejectEmployee(row.id, reason),
},
]}
bulkActions={[
{
id: "delete",
label: "Delete selected",
variant: "destructive",
onClick: (selectedIds) => deleteEmployees(selectedIds),
},
]}
/>getRowIdalone (norowActions) is enough to turn on row selection and the bulk-actions bar — an actions column only appears whenrowActionsis also supplied.- By default,
rowActionsgroup into a "..." dropdown per row (excepttype: "button"/type: "checkbox"actions, which always render inline). SetisRowActionsWithoutDropdownto render every action inline instead — this is required for avariant: "reject"action's confirm-with-reason popover to be reachable, since the reject-popover special-casing only applies to inline actions (in dropdown mode areject-variant action is just a plain menu item that callsonConfirmimmediately, with no reason prompt). onConfirm/onClickreceive{ action, row, rowIndex, sn, reason? }—reasonis only set for areject-variant action, populated from what the user typed in the popover.
Filters
Pass filterConfigs to enable a "Filters" drawer (button badge shows the active filter count)
and an active-filter chip row. Each filter's apiPayload merges into the params object passed to
apiFunction, alongside search/page_no/rows_per_page:
import { FILTER_TYPE } from "noviq-ui";
<Table
columns={columns}
apiFunction={fetchEmployees}
filterConfigs={[
{
id: "department",
label: "Department",
type: FILTER_TYPE.SELECT,
options: [
{ value: "eng", label: "Engineering" },
{ value: "sales", label: "Sales" },
],
},
{ id: "joinDate", label: "Join date", type: FILTER_TYPE.DATE_RANGE },
]}
/>;- Types:
search(text),date(single native date input),select(checkboxes, true multi-select —apiPayloadis a comma-joined string, e.g.{department: "eng,sales"}),dateRange(two native date inputs, "From"/"To" — apiPayload keys default to${id}From/${id}To, override withstartDateKey/endDateKey),month(native month input — defaults to{[id]: "YYYY-MM"}, or split viamonthKey/yearKey). - Filters are applied all-at-once via an "Apply" button in the drawer, not incrementally as each field changes.
- With
preFetchedDatathe table filters the rows itself, by the row field named in the filter'saccessorKey(default: itsid). All the active filters must match; then the search, sort and paging apply to what is left, the pager goes back to page 1, and an export writes the filtered rows.select: the field (or any item, if it is an array) is one of the chosen values, compared as text.search: the field contains the text, ignoring case.date: the same calendar day.dateRange: the day falls between "From" and "To", both included, and either end may be left open.month: the same month. A row with no value in that field matches no active filter. SetaccessorKeywhenever the filter'sidis not the row's field name. mandatory: trueon a filter config makes it non-removable (no "X" on its chip, survives "Clear all").- Clicking a chip's text reopens the drawer. Standalone,
FilterChipstakesonChipClick(without it the chips are plain text) andFilterDrawertakesopen/onOpenChangeto be controlled from outside; left out, it opens and closes itself as before. - Filters are session-only — they reset on remount/reload, unlike column settings which persist
via the opt-in
idprop. This is deliberate: filters carry more "why is this still filtered?" surprise-risk than column layout preferences. FilterDrawerandFilterChipsare also exported standalone if you're building a custom table shell, along with thebuildActiveFilter(config, rawValue)helper they're both built on.
Export
An "Export" button is shown by default (set isExportHidden to hide it). It fetches all rows
matching the current search/filters — not just the currently-loaded page — in one request, then
downloads an Excel (.xlsx, styled header row) or CSV file:
<Table
columns={columns}
apiFunction={fetchEmployees}
exportFileName="employees"
/>While an export runs, the Export button shows "Exporting…" and is disabled. The outcome is reported through
notifyonNoviqUIConfigProvider—noviq-uihas no toast system of its own, so route it into whatever your app already uses:import toast from "react-hot-toast"; // or any snackbar/notification library import { NoviqUIConfigProvider } from "noviq-ui"; <NoviqUIConfigProvider config={{ table: { responseFormat: { rowsPath: "result", totalPath: "totalCount" }, }, notify: (message, kind) => kind === "error" ? toast.error(message) : toast.success(message), }} > <App /> </NoviqUIConfigProvider>;notify(message, kind)is called once per export withkind"success"("Export complete") or"error"("Export failed"). With nonotifyconfigured nothing is announced; a failed export is still logged withconsole.error.config.tableis optional when you only wantnotify(e.g. an app whose tables all usepreFetchedData).Per-column control: set
export: falseon a column to exclude it, orexportValue={(row) => ...}for a custom cell value. Only currently-visible columns (per the "Columns" chooser, if enabled) are exported — hidden columns are skipped, matching what's on screen.preFetchedDatamode exports the filtered, sorted in-memory array directly — no extra fetch.In the Excel file every cell is the text the table shows (a date as displayed, a currency with its symbol), except an
exportValuethat returns a number, which stays a number. Each column is as wide as its widest cell, from 10 to 60 characters.responseSheetUrlskips the whole export flow and just opens a pre-generated report link instead (and hides the CSV option) — useful if your backend already produces the file.Exportand theuseTableExporthook it's built on are also exported standalone.
Status cells
A column with type: "status" shows a coloured pill. These statuses have a built-in tone —
active, true, approved, completed, resolved green; inactive, false, rejected,
cancelled, failed red; pending, queued amber; in progress blue — and anything else is grey.
They are only defaults (DEFAULT_STATUS_STYLES, with the tone class names in STATUS_CLASS):
add your own, or change these, at any of three levels.
// the whole app
<NoviqUIConfigProvider
config={{
statuses: {
styles: {
draft: "my-status-draft", // a class name
shipped: { className: "my-status-ok", label: "On its way" }, // and the text shown
pending: { label: "Awaiting review" }, // a label alone keeps pending's built-in colour
},
fallback: "my-status-neutral", // for a status with no entry (default: the grey tone)
},
}}
>
// one table
<Table statuses={{ styles: { draft: "my-status-draft" } }} … />
// one column — say a table with an approval status and a payment status that both use "pending"
{ id: "payment", heading: "Payment", accessorKey: "payment", type: "status",
statuses: { styles: { pending: "my-payment-wait" } } }Precedence, most specific first: the column, the table, the provider, the built-in tones. Your entries are added to the built-in ones, and each level merges over the one beneath it status by status and field by field (a table can change a status's class and keep the provider's label).
Keys are matched on the trimmed, lower-case text — write them as your data spells them.
in_progressis notin progress: the label shows "in progress" either way, but only the spelling you list gets your class (map both if your data has both).Your class is the only thing that colours the pill — it replaces the built-in tone rather than sitting beside it — so it wins no matter which stylesheet loads first. Use your own variables:
.my-status-draft { background-color: var(--brand-grey-100); color: var(--brand-grey-700); border-color: var(--brand-grey-300); }A
labelis what the cell shows, what an Excel/CSV export writes, and what the search box matches.renderreplaces the whole pill with your own component. It receives{ status, label, className, row }—classNameis the class the status resolved to, so you can keep the tone — and is not called for an empty status (the-placeholder shows):statuses={{ render: ({ status, label, row }) => <StatusPill value={status} owner={row.owner}>{label}</StatusPill> }}To re-theme a built-in tone without writing a class, override its custom properties (see "Theming").
A nested
NoviqUIConfigProviderreplacesstatuseslike everything else; withinheritthe two are merged.TableCellused on its own takes the samestatusesprop (and the provider's).statusVariantMap(a status → class-name map onTable) still works;statuses.stylessupersedes it.
Date and time formats
Declare how dates and times read once, on NoviqUIConfigProvider, and every place the UI shows
one follows it:
<NoviqUIConfigProvider
config={{
formats: {
date: "DD MMM YYYY", // 05 Mar 2024 (default "DD/MM/YYYY")
time: "HH:mm", // 14:30 (default "hh:mm A")
dateTime: "DD MMM YYYY, HH:mm", // 05 Mar 2024, 14:30 (default: date + " " + time)
},
}}
>All three are optional. dateTime follows a customised date and time unless you set it.
Where it applies: Table date / date-range / date-time / date-time-range / time / time-range
cells; the Excel and CSV export (so a file matches the screen); filter chips; and DatePicker,
MonthPicker and TimePicker. In your own components use the same patterns with the hook:
const { formatDate, formatTime, formatDateTime } = useDateTimeFormatters();
formatDate("2024-03-05"); // "05 Mar 2024"
formatDateTime("2024-03-05T14:30:00"); // "05 Mar 2024, 14:30"
formatDateTime(isoFromApi, { isUtc: true }); // treat a zone-less value as UTCDisplay only. Values never change shape: pickers still emit "YYYY-MM-DD", "HH:mm" and
"YYYY-MM", and filter payloads sent to your backend stay ISO. A value that can't be read as a
date or time is shown as it was, not as NaN/NaN/NaN.
Tokens
| Token | Output | Token | Output |
| -------------- | ----------------- | ---------- | ----------------------------------------- |
| YYYY / YY | 2024 / 24 | HH / H | 00–23 / 0–23 |
| MMMM / MMM | March / Mar | hh / h | 01–12 / 1–12 (12 = midnight/noon) |
| MM / M | 03 / 3 | KK / K | 00–11 / 0–11 (zero-based) |
| DD / D | 05 / 5 | mm / m | 07 / 7 |
| dddd / ddd | Tuesday / Tue | ss / s | 09 / 9 |
| A / a | PM / pm | [text] | text, literally |
Anything else is printed as written. Escape words that contain a token letter — "DD MMM [at]
HH:mm" — exactly as you would in moment. KK is the one token moment doesn't have; it's the
zero-based 12-hour clock where midnight and noon read 00.
How the pickers use it
DatePickershowsformats.date; the calendar days are labelled the same way.displayFormat="…"overrides it for one picker.MonthPickershowsformats.datewith the day removed (DD/MM/YYYY→MM/YYYY,YYYY-MM-DD→YYYY-MM,dddd, DD MMMM YYYY→MMMM YYYY).displayFormatoverrides it.TimePickertakes both its clock and its text fromformats.time:HH:mmis a 24-hour picker,hh:mm Aa 12-hour one listing12, 01 … 11,KK:mm Aa 12-hour one listing00 … 11. An explicithourCycleprop always wins, and a pattern that contradicts the clock is ignored. With noformats.timeconfigured it is the library defaulthh:mm A— the same 12-hour pattern the Table uses (andhourCycle={12}alone uses the zero-basedKK:mm A).
Regional settings
Three more options on formats set the language and conventions of what the UI shows:
<NoviqUIConfigProvider
config={{
formats: {
locale: "de-DE", // BCP-47 tag (default "en-IN")
currency: "EUR", // ISO 4217 code (default "INR")
weekStart: 1, // 0 = Sunday … 6 = Saturday (default: the locale's, else Sunday)
date: "dddd, D. MMMM YYYY",
},
}}
>localesets the language of month and weekday names (MMMM,MMM,dddd,ddd, the calendar's month list and weekday headings, a month filter's chip), howcurrencycells group digits and place the symbol (1.234.567,50 €), and — unlessweekStartis set — which day the calendar week starts on. English locales keep the built-in names, so a date reads the same on every browser. Digits are not translated; the AM/PM marker is, throughtext.timeAm/text.timePm.currencyis what acurrencycolumn uses when it sets nocurrencyof its own.weekStartoverrides the locale's first day of the week.
Unset, everything stays as it was: English names, lakh/crore grouping (₹12,34,567.50), INR,
Sunday first. A locale Intl can't read, a currency that isn't three letters, or a weekStart that
isn't a whole number 0–6 throws a clear error from the provider; a bad currency code inside row
data shows the code before the number instead of breaking the table. useDateTimeFormatters()
returns the resolved values as formats.locale, formats.currency and formats.weekStart.
Nested providers replace, unless you say inherit
A NoviqUIConfigProvider inside another one replaces the outer config for its subtree. To change
only the formats for one screen, add inherit and it is laid over the parent's config instead:
<NoviqUIConfigProvider inherit config={{ formats: { date: "DD MMM YYYY" } }}>
{/* the app's table responseFormat, notify and text all still apply here */}
</NoviqUIConfigProvider>formats, text and the table's requestParams merge key by key (the child's keys win); notify
and anything else the child sets replaces the parent's; what the child leaves out is inherited,
including table.responseFormat (a child responseFormat replaces it as a whole — the two shapes
are never mixed). A key set to undefined in the child does not wipe the inherited value. Without
inherit, repeat what is needed: a <Table apiFunction> under a replacing provider with no
responseFormat would throw.
Not covered
The browser's own <input type="date|time|month"> (Input type="date", the date fields inside the
filter drawer) is rendered by the browser in the user's locale and can't be reformatted. Use
datePicker / timePicker / monthPicker where the format has to match.
Text and translation
Everything the components say in English — the search placeholder, "No data found", the pager,
"3 rows selected", the picker buttons, validation messages, export results — comes from one
dictionary, and config.text replaces any of it:
<NoviqUIConfigProvider
config={{
text: {
tableSearchPlaceholder: "Buscar...",
tableEmpty: "No se encontraron datos",
paginationSummary: "Mostrando {start} a {end} de {total} resultados",
paginationPage: "Página {page} de {pages}",
bulkSelectedOne: "{count} fila seleccionada",
bulkSelected: "{count} filas seleccionadas",
dateToday: "Hoy",
},
}}
>- Any subset. A key you leave out keeps its English default, so you can translate screen by
screen, or only reword one message.
import { DEFAULT_TEXT } from "noviq-ui"is the full list of keys with their defaults;TextKeyis its key type, and typing your dictionary asRecord<TextKey, TextValue>makes the compiler tell you when a release adds a key. {placeholders}mark where the component puts a value ({count},{start},{page},{label},{date},{min},{browse}…). Move them wherever your language needs them. A placeholder you misspell is left as written, so it shows on screen instead of vanishing.- A function instead of a string gets those values and returns the text — for plurals a
template can't express:
bulkSelected: ({ count }) => new Intl.PluralRules("ru").select(Number(count)) === "few" ? … : …. A function that throws or returns a non-string is reported (in development) and the English default is used, so a bad translation can't stop a component from rendering. bulkSelectedOne/bulkSelected(andinputFilesSelectedOne/inputFilesSelected) are a singular/plural pair; the library picks one by count.- Props still win.
placeholder,searchPlaceholder,emptyMessage,title,submitLabel,cancelLabel,loadingLabel,rejectTextandnoOptionsMessageoverride the text for that one component, exactly as before. - Where the keys live, by prefix:
table…/pagination…/bulk…/columns…/column…/filter…/export…/status…(Table and its parts),reject…(the reject-with-reason popover and its validation),time…/date…/month…(the pickers;timeAm/timePmare the AM and PM markers wherever a time is shown),form…/drawer…(FormFooter, FullPageSection, Drawer),input…(placeholders, select, file and Excel upload). - Not in the dictionary: copy that is your data — column headings, filter labels, row-action
labels, status values (other than
true/false, shown as Active/Inactive), theForm's field labels — which you already write in your own language; developer-facing errors and warnings (they stay English); and the "Unsupported input type" fallback. - Nested providers replace, as with
formats: aNoviqUIConfigProviderinside another one does not inherit itstext— unless it hasinherit, which merges the two key by key.
To find strings you haven't translated, render with every default wrapped and look for any that come out bare:
import { DEFAULT_TEXT } from "noviq-ui";
const pseudo = Object.fromEntries(
Object.entries(DEFAULT_TEXT).map(([k, v]) => [k, `«${v}»`])
);
// <NoviqUIConfigProvider config={{ text: pseudo }}> … anything shown without « » is still hard-codedMonth and weekday names, number and currency formats follow formats.locale (see "Regional
settings"); text is for the words around them.
Currently available components
<Input />— type-switching input field. Supportedtypes:text,email,password,textArea,search,number,checkbox,radio,switch,select,multiSelect,date,time,month,datePicker,timePicker,monthPicker,color,file,multipleFile,excelUpload. Supportslabel,required,helper,error.<Button />— variants (default,outline,destructive,secondary,ghost,link) and sizes (sm,md,lg,icon)<ScrollArea />— styled scroll viewport wrapper<Drawer />— portal-based slide-over panel (right/left/top/bottom, sizessm/md/lg)<Modal />— portal-based centered modal with enter/exit animation (sizessm/md/lg/xl/auto)<Label />— styled<label>wrapper<Switch />— toggle switch, keyboard accessible<TimePicker />— time field with scrollable hour/minute columns; 12-hour with an AM/PM column by default, or 24-hour (see above)<DatePicker />— calendar dropdown for a date, with min/max and keyboard support (see above)<MonthPicker />— month/year grid (see above)<FormFooter />— Cancel/Save button row for a form<FullPageSection />— full-page form layout: back arrow + title, card, sticky footer (see above)<Form />— config-driven form renderer (inputList+ a Formik instance, or any object with theFormControllershape)<Badge />— small status/label pill (variants:default,secondary,destructive,outline)<DropdownMenu />/<DropdownMenuItem />— portal-positioned dropdown menu<Table />— sortable, searchable, paginated data table with column management (show/hide/ reorder/pin, optionally persisted tolocalStorage), optional row selection/row actions/bulk actions, optional filters, and Excel/CSV export (see above).apiFunction(server-driven) orpreFetchedData(client-controlled) data sources;type-driven cell formatting (date,dateRange,dateTime,time,duration,currency,status, plus a customcellrender function).<NoviqUIConfigProvider />/useNoviqUIConfig()— declares your backend's response shape (and, optionally, the request param names) once for everyTablebelow it; required for anyTableusingapiFunction(see "Breaking change in 3.0.0" above).<ColumnSelector />— the "Columns" chooser panelTableuses internally; also exported standalone if you're building a custom table shell.<Checkbox />— small styled checkbox with full keyboard/ARIA support, used internally byTable's row-selection column; also exported standalone.<RowActionsMenu />— per-row action renderer (inline buttons/checkbox/reject-popover, or grouped into a dropdown); used internally byTable's auto-injected actions column, also exported standalone for a custom table shell.<RejectAction />— confirm-with-reason popover button (validates the reason: required, min 4 chars, no leading space, no repeating characters, not digits-only); used byRowActionsMenuforvariant: "reject"actions, also exported standalone.<BulkActionsBar />— "N selected" bar with bulk-action buttons and a "Clear" control; used internally byTablewhengetRowIdis set, also exported standalone.<FilterDrawer />— self-contained "Filters" trigger button + drawer (5 filter types, see above); used internally byTablewhenfilterConfigsis set, also exported standalone.<FilterChips />— active-filter chip row with per-chip remove and "Clear all"; used internally byTable, also exported standalone.<Export />— "Export" dropdown (Excel/CSV, or a plain link whenresponseSheetUrlis set); used internally byTable, also exported standalone alongside theuseTableExporthook.
More components will be added in future releases.
Theming
Components are styled with plain CSS driven by :root custom properties (src/styles/tokens.css),
not a CSS framework. Everything noviq-ui puts in the page's CSS namespace is prefixed, so it can
never collide with your own stylesheet: classes are nq-…, custom properties --nq-…, keyframes
nq-…. (A test fails the build if one isn't.) Override a token in your own CSS to re-theme:
:root {
--nq-primary: #7c3aed;
--nq-radius: 10px;
}| Token | Default | Is |
| ----------------------------------------------------------- | ----------------------------- | ----------------------------------------------- |
| --nq-primary / --nq-primary-hover | #02699b / #025a85 | brand colour, primary buttons, focus, selection |
| --nq-danger / --nq-danger-hover | #ff0000 / #e60000 | destructive actions, errors |
| --nq-heading / --nq-text-color | #272727 / #6b6b6b | headings and labels / body text |
| --nq-muted / --nq-muted-hover | #6b7280 / #4b5563 | secondary text and icons |
| --nq-light | #ffffff | surfaces (cards, inputs, popups) |
| --nq-secondary-background | #f2f2f2 | disabled fields, soft fills |
| --nq-surface-hover | #e6f1fe | hovered rows, menu items |
| --nq-border-color | #e0e5eb | borders and dividers |
| --nq-radius / --nq-radius-sm | 6px / 4px | corner radii |
| --nq-shadow | 0 20px 40px rgba(0,0,0,.15) | modals, drawers, popups |
| --nq-overlay-bg | rgba(0,0,0,.5) | the backdrop behind a modal or drawer |
| --nq-font-size | 14px | base font size |
| --nq-z-sticky, -loading, -bar, -overlay, -popover | see below | the z-index scale |
Each built-in status tone is three more tokens — its fill, its text and its border — so a status pill can be re-themed from your own CSS (see "Status cells"):
| Tone | Fill | Text | Border |
| --------- | -------------------------- | --------------------------- | ----------------------------- |
| success | --nq-status-success-bg | --nq-status-success-text | --nq-status-success-border |
| danger | --nq-status-danger-bg | --nq-status-danger-text | --nq-status-danger-border |
| warning | --nq-status-warning-bg | --nq-status-warning-text | --nq-status-warning-border |
| info | --nq-status-info-bg | --nq-status-info-text | --nq-status-info-border |
| default | --nq-status-default-bg | --nq-status-default-text | --nq-status-default-border |
:root {
--nq-status-success-bg: #e6f7ee;
--nq-status-success-text: #0b6b3a;
--nq-status-success-border: #b7e4cb;
}The defaults are the colours the pills have always had; danger's text follows --nq-danger, and default
follows --nq-secondary-background, --nq-muted and --nq-border-color.
Coming from 4.6 or earlier, where the tokens had no prefix (--primary, --radius,
--border-color, --shadow, --z-overlay…): rename your overrides — the new name is the old one
with nq- after the dashes — or import the bridge, which makes each --nq-* token follow your
old-named property when you define one:
import "noviq-ui/style.css";
import "noviq-ui/legacy-tokens.css"; // optional: only if you themed through the old namesDon't import the bridge otherwise: it makes noviq-ui read your app's own --primary, --radius,
--shadow… whatever they mean there — the very coupling the prefix removes.
Stacking and z-index
Every layer comes from one scale in tokens.css; no component has its own number.
| Layer | Token | Default |
| ------------------------------------------------ | ---------------- | ------------------------------- |
| a table's pinned columns | --nq-z-sticky | 2 |
| a table's loading veil | --nq-z-loading | 5 |
| a sticky page bar (FullPageSection's footer) | --nq-z-bar | 6 |
| modals and drawers | --nq-z-overlay | 1200 |
| pickers, menus, select lists, the reject popover | --nq-z-popover | --nq-z-overlay + 310 (1510) |
- Overlays stack in the order they open, not the order they were mounted: each modal or drawer takes the next step of 10 above the highest one open (a drawer's panel is one above its backdrop). So a Drawer opened from a Modal, a Modal opened from that Drawer, and a Drawer opened by a Table inside either all end up on top of the one that opened them — and stay put when a lower one closes.
- Popups are above every overlay, however deep: pickers,
DropdownMenu, the select lists, the Export menu, the page-size menu and the reject popover all use--nq-z-popover. Modal,Drawerand every popup are portaled to<body>, so a wrapper in your layout with atransform,filter,containor its ownz-indexcan't trap them or shift them off the viewport.- Your own layers above 1200 (a header at
z-index: 2500, say) would paint over a modal. Raise one token — the popups follow it:
:root {
--nq-z-overlay: 3000;
}Keep your toast/notification layer above --nq-z-popover if you want it over modals.
License
noviq-ui is proprietary software of Satellite Key IT Solutions. All rights reserved: using it requires a written agreement with Satellite Key IT Solutions — being public on npm and GitHub does not grant one. See LICENSE.
Third-party notices
The package bundles open-source code (React is the one external dependency), each part under its
own licence. Those licences are reproduced in dist/THIRD-PARTY-NOTICES.md inside the published
package — generated by the build from what was actually bundled.
Contributing
Bug reports and ideas are welcome as issues; code contributions are accepted from Satellite Key IT Solutions staff and authorised partners. How to set up, what to run before a pull request, and the conventions the tests enforce are in CONTRIBUTING.md.
Code of conduct
This project follows the Contributor Covenant. See CODE_OF_CONDUCT.md.
