sn-react-pack

A React component library for ServiceNow — type-aware fields, record forms, lists, charts, diagrams, schedulers, and the data hooks/services that back them, all built on MUI.

Alpha. This is an early preview (1.0.0-alpha.x, published under the alpha dist-tag). The public surface (index.ts) is the supported contract, but APIs may still change before 1.0.0.

Requirements

• React 19 and React DOM 19 — the only peer dependencies; the host app provides them.
• The companion ServiceNow app (scope x_snrp_ui) installed on your instance. The library's metadata / access / current-user features call that app's scoped REST endpoints (/api/x_snrp_ui/rhino/*); users need the x_snrp_ui.user role. Standard CRUD/list/aggregate features use the platform Table API and work without it.

The library is designed to run inside a ServiceNow UI page (same-origin requests, session CSRF token). It is not intended for use outside an authenticated ServiceNow session.

Install

npm install sn-react-pack
# peer dependencies (if your app doesn't already have them):
npm install react react-dom

@mui/material, @mui/lab, @emotion/react, @emotion/styled, @mui/x-charts, @mui/x-data-grid, @mui/x-scheduler, @mui/x-tree-view, @xyflow/react, @dnd-kit/* and react-router-dom ship as dependencies — you don't install them separately. Only react and react-dom are peers, since the host app must provide a single React instance.

The scheduler relies on pre-release Base UI packages. If you hit version-resolution issues, mirror the overrides block from this package's package.json in your app's root package.json.

Quick start

Wrap your app in ServiceNowProvider, then use any component or hook:

import { ServiceNowProvider, useRecord } from 'sn-react-pack';

function IncidentTitle({ sysId }: { sysId: string }) {
  const { data, loading, error } = useRecord('incident', sysId);
  if (loading) return <span>Loading…</span>;
  if (error) return <span>{error.message}</span>;
  return <span>{data?.short_description}</span>;
}

export function App() {
  return (
    <ServiceNowProvider>
      <IncidentTitle sysId="<a sys_id>" />
    </ServiceNowProvider>
  );
}

Theme the library with a standard MUI ThemeProvider + createTheme — the package ships sensible defaults via styled() slots and useThemeProps, and exposes Sn* component keys for overrides.

What's inside

Fields, RecordForm / dialogs / drawers, RecordList, ConditionBuilder / FilterPanel / SegmentFilter / PeriodFilter, RecordTree, cards (AgendaCard with eyebrow, accent and imminent cue, …), charts (Counter with lookback and inverted trends, Gauge, BarChart, LineChart with multi-table sources and end labels, …), diagrams (RecordMap), schedulers, navigation (AppShell, Navbar, LeftNav), drag-and-drop composites, record views, and data hooks (useRecord, useRecords, useMergedRecords, useTimeSeries / useMultiTimeSeries, useRecordMetadata, useAccess, useCurrentUser, …). See the full inventory and live demos in the Component Explorer.

License

Apache-2.0