Skip to content

Patterns · Technical infrastructure

AuditLogViewer

Security and audit events in a table: actor, action, target, IP and device, a details drawer, filters, export and paging.

@rookcom/monarch-react/collaborationPattern

Workspace audit log

TimeActorActionTargetIP and deviceDetails
Ana LopezChanged a member’s roleBen Okafor203.0.113.24Firefox on macOS
Chloé MartinSigned in—198.51.100.8Safari on iPhone
Retention policyAutomationDeleted 14 expired exportsScheduledExports—
Deploy keyAPIUpdated a webhookBilling events192.0.2.44API client

Showing 4 events

Usage examples

The example at the top of the page is the only one for this component.

Purpose

Shows who did what, to what, from where and when, for workspace admins and security reviews. Each row opens a drawer with the full record: field-level before and after, reason and any payload.

Use when

  • Workspace or product settings › Audit log.
  • Security events: sign-ins, key use, permission changes.
  • Any immutable change history that needs export.

Avoid when

  • A record’s own history in context: use ActivityTimeline.
  • Editable data: audit entries are read-only.

Design principles

  • Absolute times in the table (audits are compared across days); relative time in the drawer for context.
  • People, automations, systems and API keys are told apart in text, never colour alone.
  • Changes are a structured before and after, not raw JSON; raw payloads go in details when needed.
  • Filtering, fetching and the export file are the product’s: the viewer offers slots and callbacks.

API reference

import { AuditLogViewer, auditLogToCsv } from '@rookcom/monarch-react/collaboration';
ExportKindRenderingRoot class
AuditLogViewercomponentclient.mn-audit-log-viewer
auditLogToCsvutilityclient–

Built on Monarch Table, Sheet, DescriptionList and LoadMore.

auditLogToCsv(rows) builds an RFC 4180 CSV and defuses spreadsheet formulas; use it for client-side exports of what is loaded, or export on the server for everything.

selectedId / defaultSelectedId / onSelectedChange control the open drawer, e.g. to deep-link an event.

The ref is forwarded to the root <div>.

Generated from the TypeScript declarations of packages/react/src/patterns/technical/audit-log-viewer.

Properties

AuditLogViewer

Security and audit events in a table: time, actor, action, target, IP and device, with a details drawer (field changes, reason, payload), a filters slot, an export action and cursor pagination.

PropTypeDescription
events requiredreadonly AuditLogEvent[]Loaded events, newest first.
classNamestring
columnsreadonly AuditLogColumn[]Columns to show, in order. Default all five. Hidden columns stay in the details drawer.
defaultSelectedIdstring | null
density"compact" | "comfortable"`compact` table rows. Default `comfortable`.
emptyReactNodeReplaces the default empty text, e.g. an EmptyState with a clear-filters action.
errorReactNodeFailure, e.g. an InlineErrorRetry or a permission note. Replaces the table.
exportingbooleanThe export is running: the button shows a spinner.
filtersReactNodeFilter controls (FilterBar, Select, SearchInput). The product filters or refetches `events`.
hasMorebooleanCursor pagination: another page exists.
idstring
loadingbooleanFirst load: shows a skeleton.
loadingMoreboolean
loadMoreErrorboolean
localestring
messagesPartial<AuditLogViewerMessages>
nowDateInput
onExport(() => void)Shows an Export button. Build the file with `auditLogToCsv` or on the server.
onLoadMore(() => void)
onSelectedChange((id: string | null) => void)
renderDetails((event: AuditLogEvent) => ReactNode)Extra drawer content for an event, after the built-in fields.
selectedIdstring | nullThe event whose details drawer is open, controlled.
timeZonestring

Variants

PropValuesDescription
columns'['time', 'actor', 'action', 'target', 'origin']''any subset'Columns shown, in order. Hidden fields still appear in the drawer.
density'comfortable''compact'Table row height.

States

StateExposed asBehaviour
Loading–Skeleton rows in place of the table.
Error–The error node (for example a permission note) replaces the table.
Empty–“No events match”, or the empty node (an EmptyState with Clear filters).
Selectedaria-selected="true"The row whose drawer is open.
Exporting–The export button shows a spinner and stays focusable.

Interaction behaviour

  • Details opens a side drawer with every field, the changes table, details and renderDetails(event).
  • Closing the drawer (Escape, Close or outside click) returns focus to the row’s Details button, also when the product opened it.
  • Export calls onExport; LoadMore calls onLoadMore for the next cursor page.

Keyboard support

KeysAction
TabMoves through filters, Export, each row’s Details button and Load more.
Enter / SpaceOpens the details drawer for the row.
EscapeCloses the drawer.

Accessibility

Role
table, with a dialog for details
Accessible name
The table is labelled “Audit log” (messages.caption); the drawer is named by the event’s action.
  • Each Details button is named with its row’s action (“Details Changed a member’s role”).
  • The changes table uses row headers for field names.
  • Times are <time datetime> elements.
  • Actor kinds are text tags (“Automation”, “System”, “API”).

Responsive behaviour

  • A container query hides IP and device below 44rem; below 32rem the target is hidden and the time moves under the action. Everything stays in the drawer.
  • The toolbar wraps; the table scrolls horizontally inside its wrapper if it still does not fit.
  • The drawer becomes full width on phones (Sheet).

Theme support

  • Table tokens from DataTable; IP addresses in font-mono; before values in danger-strong, after values in success-strong.

Do and don't

Do

  • Write actions as short sentences in the past tense.
  • Record and show the reason when the product asks for one.
  • Show approximate locations honestly (“approximate”).

Don't

  • Do not let admins edit or delete entries from this view.
  • Do not show secrets or full tokens in details.
  • Do not export only the loaded page without saying so; export on the server for the full range.

Dependencies

KindDepends on
npm packagesreact
Monarch componentsAvatar, Button, RelativeTime, DescriptionList, DataTable, LoadMore, Skeleton, Sheet

Testing coverage

  • Labelled table with all columns, actor kinds and unknown actors.
  • Details buttons named by their row.
  • Drawer with fields, the changes table and payload; Escape closes and returns focus.
  • Controlled selection and renderDetails.
  • Filters slot, export (and exporting), cursor pagination.
  • Column choice keeps hidden fields in the drawer; loading, error and empty.
  • auditLogToCsv quoting, escaping and formula defusing.
CheckCovered
Axe in jsdomYes
Server renderingYes
Browser suitesVisual baselines: /__gallery/audit-log-viewer (table and open drawer); Cross-browser axe: /components/audit-log-viewer

Tests: packages/react/src/patterns/technical/audit-log-viewer