DocumentViewer
<co-document-viewer>DocumentViewer shows a scanned or outside document page by page with zoom, and lets staff highlight a line or comment on it, listing the annotations beside the page.
import { DocumentViewer } from 'health-components';
Examples
Showcase
Read Only
Could Not Open
Usage
<DocumentViewer title="Discharge summary" pages={pages} annotations={notes} />
When to use
- Outside records, discharge summaries, faxed consult letters, prior-auth packets.
When not to use
- Incoming fax triage: FaxDocumentViewer.
Variants and states
| Variant | What it is |
|---|---|
| viewing | Page, zoom 50 to 200 %, page count. |
| highlight | Yellow mark on a line. |
| comment | Blue mark with the text in the side list. |
| adding | Click a line, then type a comment or Highlight. |
| readOnly | Lock note; no adding. |
| error / empty | Empty state with the reason. |
Clinical values
Every number renders through CareOS.ClinicalValue and CareOS.fmt (the clinical-values builder), matched by LOINC; measures that table lacks (NT-proBNP, lactate, vancomycin trough, CrCl, PHQ-9, per-kg doses) use a local table with the same rules: tabular figures, the unit always shown, fixed decimals per measure (potassium 1, sodium 0, creatinine 2), the reference range in the title or beside it, and H, L, HH or LL flags in words for screen readers. The flag says where the number sits against the adult reference range in the rules table; it does not say the number was measured correctly.
Accessibility
- Page changes are announced (aria-live).
- Marks are focusable.
Do and don't
- Do: Say who annotated and when.
- Don't: Change the source document: annotations sit on top.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
pages | DocumentPage[] | none (empty state) | Pages |
annotations | DocumentAnnotation[] | none | Initial annotations; the viewer keeps its own copy |
onAnnotationsChange | (annotations: DocumentAnnotation[]) => void | none | Called with all annotations after one is added |
page | number | uncontrolled | Shown page index (controlled), from 0 |
defaultPage | number | 0 | Initial page index |
onPageChange | (page: number) => void | none | Called with the new page index |
onDownload | () => void | none | Called by Download |
title | string | none | Card title |
subtitle | string | none | Card subtitle (source, received) |
user | string | 'You' | Author name on new annotations |
readOnly | boolean | false | No adding annotations |
error | string | none | Why the document could not be opened; shows the error state |
maxHeight | number | 520 | Height of the page area in px |
rangeContext | RangeContextId | the global context, else 'outpatient' | Which shared reference range flags use; the lab range on a result still wins |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-document-viewer>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
<co-document-viewer page="…" default-page="…" [pages]="pages" (co-annotations-change)="onAnnotationsChange($event.detail)"></co-document-viewer>
| Kind | Name | Description |
|---|---|---|
| property / JSON attribute | pages | Pages; default none (empty state) |
| property / JSON attribute | annotations | Initial annotations; the viewer keeps its own copy; default none |
| attribute | page | Shown page index (controlled), from 0; default uncontrolled |
| attribute | default-page / defaultPage | Initial page index; default 0 |
| attribute | title | Card title; default none |
| attribute | subtitle | Card subtitle (source, received); default none |
| attribute | user | Author name on new annotations; default 'You' |
| attribute | read-only / readOnly | No adding annotations; default false |
| attribute | error | Why the document could not be opened; shows the error state; default none |
| attribute | max-height / maxHeight | Height of the page area in px; default 520 |
| attribute | range-context / rangeContext | Which shared reference range flags use; the lab range on a result still wins; default the global context, else 'outpatient' |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| event | co-annotations-change | Called with all annotations after one is added; default none (React: onAnnotationsChange) |
| event | co-page-change | Called with the new page index; default none (React: onPageChange) |
| event | co-download | Called by Download; default none (React: onDownload) |