Skip to content

API reference ​

umlimator is one ES module with no dependencies, no build step and no network calls. It draws a map model into any element, and its functions that read a model run in Node as well as in a browser. The types are hand-written in lib/umlimator.d.ts; these pages explain each export. The history of every change is in the changelog.

bash
npm install umlimator
js
import { render } from 'umlimator';
import 'umlimator/theme.css';

const map = render(document.getElementById('map'), model, {
  on: { select: e => console.log(e.target) },
});

Entry points ​

ImportFileWhat it gives you
umlimatorlib/umlimator.jsMaps: every function below. A typed view (a diagram type) draws as plain cards, with a warning.
umlimator/alllib/umlimator-all.jsThe same exports, and every diagram type drawn in its own notation. See Typed diagrams.
umlimator/theme.csslib/umlimator-theme.cssThe default --um-* palette, light and dark, and the fonts. Optional: a host may set the variables itself.
umlimator/schema.jsonlib/umlimator.schema.jsonThe model's JSON Schema, for editors and validators. See Model and schema.
umlimator/elementlib/umlimator-element.jsThe <umlimator-map> custom element. See Element and plugins.
umlimator/markdown-itlib/umlimator-markdown-it.jsA markdown-it plugin (VitePress) for umlimator fenced blocks.
umlimator/remarklib/umlimator-remark.jsA remark plugin (Docusaurus, MDX) for the same blocks.

umlimator and umlimator/all share one set of types and one API: switch the import to draw diagram types, and nothing else changes.

From a CDN, with no install:

html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/umlimator@0.44.0/lib/umlimator-theme.css">
<script type="module">
  import { render } from 'https://cdn.jsdelivr.net/npm/umlimator@0.44.0/lib/umlimator.js';
</script>

Functions ​

FunctionNeeds a browserWhat it doesPage
render(container, model, options?)yesDraws a model into an element and returns a Handle.render
mountPage(container, model, options?)yesThe whole standalone viewer the CLI writes.render
layout(model, viewId, options?)noOne view's geometry: card boxes and line routes.render
check(model, viewId, options?)noThe layout check on that geometry: overlaps, crossings, detours, misplaced labels.render
validate(model)noThe model's own errors and warnings, each with where it is.apply and commands
migrate(model)noThe model at the schema version this release reads.model and schema
apply(model, commands)noThe next model after a transaction of commands.apply and commands
history(model, limit?)noUndo and redo for a host that applies models.apply and commands
references(model, id)noEvery place a model names an element.apply and commands
rules(model)noEvery rule in model.rules the model breaks, view by view.apply and commands
diff(before, after)noWhat changed between two models, as one model to draw.apply and commands
drift(model, observed)noThe map against the traffic seen: lines nobody drew, lines that carried nothing.apply and commands
describe(model, viewId)noA view in plain sentences.apply and commands
paths(model, viewId, from, to)noEvery card and line on a path between two cards.apply and commands
reach(model, viewId, from, options?)noWhat a card leads to, or what leads to it.apply and commands
critical(model, viewId, options?)noThe slowest or costliest path along a view's lines.apply and commands
whatIf(model, viewId, options)noWhat loses its way when cards are taken out.apply and commands
otlpSpans(otlp)noThe spans of an OpenTelemetry trace, ready for replay().events and state
sequenceFromTrace(model, spans, options?)noA trace kept as a numbered view of the model.events and state

None of them changes the model it is given: each one that returns a model returns a new one.

Types ​

GroupTypesPage
DrawingRenderOptions, Handle, ExportOptions, Geometry, CheckIssuerender
The modelMapModel, MapNode, MapEdge, MapView, Shape, Badge, WireKind, Element, Ref, Selector, LensSelector, Lens, Rule, Story, StoryStepmodel and schema
Changing and reading a modelCommand, History, Reference, Problem, RuleBreak, DiffResult, Observed, DriftResultapply and commands
Events, state and marksEvents, Change, Hint, MapState, StoryPlayer, Overlay, CardMark, LineMark, Lit, Span, Replayevents and state
The elementUmlimatorMapelement and plugins
Diagram typesUmlClassElementType, C4ViewType, BpmnElementProps and the rest of each type's vocabularytyped diagrams

Pages ​

  • render: render(), the Handle it returns, mountPage(), and layout() and check() in Node.
  • Model and schema: what a model holds, the JSON Schema, and migrate().
  • Apply and commands: changing a model with apply() and history(), and reading it with validate(), rules(), diff(), drift(), describe(), paths(), reach(), critical() and whatIf().
  • Events and state: the events a map emits, MapState, layers of marks, stories, tours and trace replays.
  • Element and plugins: <umlimator-map>, and the markdown-it and remark plugins.
  • Typed diagrams: umlimator/all, the typed element envelope and each diagram type's vocabulary.