Koala UIDocument Fields
ProReview what was read off a document: a box on the page for every extracted field, linked to a list of values you can correct, with confidence shown only where it is low.
Installation#
Usage#
The component reads nothing itself. Hand it the fields your extraction returned, each with its value, its confidence and a box in fractions of the page, so the boxes stay put at any zoom.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import {
DocumentFields,
DocumentFieldsPreview,
DocumentFieldsBoxes,
DocumentFieldsPanel,
DocumentFieldsReview,
DocumentFieldsList,
DocumentField,
DocumentFieldLabel,
DocumentFieldValue,
DocumentFieldOriginal,
DocumentFieldConfidence,
DocumentFieldAction,
} from "@/components/ui/document-fields"Row layout#
For a record page with room to spare, give each field one line: the label on the left, the value from the middle, the confidence at the end. A flagged row takes a warning tint and an action slot for the fix, and the review line stays quiet when nothing needs a look.
Confidence#
A field you can trust shows nothing until you hover, focus or pick it. Only a field below its threshold shows a figure at rest, in the warning colour, on the row and on its box. Set one threshold on the root and raise it for the fields that must be near certain, like an IBAN.
Corrections#
Put a control in the value to fix what was misread. Once the value differs, mark the field corrected: the flag clears, its box turns to the success colour and the extracted value stays below, struck through, so the change can be checked.
API reference#
DocumentFields
The root and the state every part reads: the selected field, the one under the pointer or focus, and the default threshold. Lays the preview and the panel side by side, and stacks them when there is no room. Every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | null | - | The selected field, when you control it. Selecting from outside scrolls both the box and the row into view. |
| defaultValue | string | null | null | The field selected on the first render. |
| onValueChange | (value: string) => void | - | A field was picked in the list, on the page or with the review buttons. |
| threshold | number | 0.8 | Confidence below this flags a field. A field can set its own. |
| layout | "stacked" | "row" | "stacked" | stacked puts the label above the value, for a narrow panel beside the preview. row gives each field one line: the label on the left, the value from the middle, the confidence at the end, with a rule between rows. |
| density | "comfortable" | "compact" | - | Row padding and the gaps. Reads DensityProvider when unset. |
DocumentFieldsPreview
A FilePreview sized for the layout, with every FilePreview prop. With no children it renders a FilePreviewViewport and DocumentFieldsBoxes; pass your own to add a header or a toolbar.
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | - | The document: an image, a PDF or an SVG. |
| file | Blob | null | - | The document as a file, in place of src. |
DocumentFieldsBoxes
Draws a box for every field that has one, on the page it belongs to, inside any FilePreview. The boxes follow zoom, fit and rotation. Hover a box to light up its row, press it to select the field. The selected box carries one ink frame that travels from field to field.
DocumentFieldsPanel
The column beside the preview. Holds DocumentFieldsReview and DocumentFieldsList, and scrolls the list when it is taller than the preview.
DocumentFieldsReview
How many fields still need a look, with buttons to the previous and the next one. When nothing is flagged it is one quiet line and the buttons go away.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | (count: number, total: number) => ReactNode | - | The count line, from the flagged fields and all of them. Use it to translate. |
| previousLabel | string | "Previous field to check" | Names the previous button for a screen reader. |
| nextLabel | string | "Next field to check" | Names the next button for a screen reader. |
DocumentFieldsList
The fields, built on Radix Toggle Group as a radio group: arrow keys walk the rows and the focused row is selected. N and P jump to the next and previous flagged field. Forwards Toggle Group root props.
DocumentField
One extracted field. Compose DocumentFieldLabel, DocumentFieldValue, DocumentFieldOriginal and DocumentFieldConfidence inside it; a control in the value stays usable and focusing it selects the field.
| Prop | Type | Default | Description |
|---|---|---|---|
| value* | string | - | The field's key, matched by the root's value. |
| box | { x: number; y: number; w: number; h: number } | - | Where the value sits, as fractions of the page from 0 to 1. Without it the field has no box. |
| page | number | 1 | The page the box is on, for a PDF. |
| confidence | number | - | How sure the extraction is, from 0 to 1. |
| threshold | number | - | Overrides the root's threshold for this field, for one that must be near certain, like an IBAN. |
| corrected | boolean | false | Someone changed the value. Clears the flag and shows DocumentFieldOriginal. |
| disabled | boolean | false | Skips the row with the keyboard and stops it being selected. |
DocumentFieldLabel
The field's name. Names the row for a screen reader, with the value.
DocumentFieldValue
The value as read, or a control to correct it, such as an InputRoot.
DocumentFieldOriginal
The value as it was extracted, struck through. Renders only once the field is corrected, so it can always be in place.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | "Extracted" | Read before the old value by a screen reader. |
DocumentFieldConfidence
Nothing at rest when the field is above its threshold: the figure shows quietly on hover, focus and selection. Below it, a warning badge with the figure; once corrected, a note.
| Prop | Type | Default | Description |
|---|---|---|---|
| format | (confidence: number) => string | - | Writes the figure. A rounded percentage by default. |
| label | string | "Confidence" | Read before the figure by a screen reader. |
| correctedLabel | ReactNode | "Corrected" | Shown for a corrected field. |
DocumentFieldAction
A slot under the value for what to do about a flagged field, such as a button to confirm it. Its controls stay usable, and focusing one selects the field.