minifieldLABSDocs
Browse docs
DocumentationMagicBox

API reference

Component props, controller methods, and extracted source spans.

Use MagicBox for the complete interface or useMagicBox for your own controls. Both share the same extraction and source-span types.

MagicBoxProps

T is the extracted value type. TSchema is the schema you pass to your extractor. See React integration for controlled input and result handling.

MagicBoxProps<T = unknown, TSchema = unknown>

Field Type Required
id string No
sourceTitle string No
className string No
style CSSProperties No
rootProps Omit<ComponentPropsWithoutRef<"div">, "children" | "dangerouslySetInnerHTML"> & { [key: `data-${string}`]: string | number | boolean | undefined; } No
theme "dark" | "light" | "auto" No
unstyled boolean No
disabled boolean No
labels Partial<MagicBoxLabels> No
name string No
rows number No
maxLength number No
textareaProps Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue" | "onChange" | "id" | "name" | "rows" | "maxLength" | "disabled"> No
renderValue (span: MagicBoxSpan<T>, source: string) => ReactNode No
onSelectionChange (span: MagicBoxSpan<T>) => void No
value string | undefined No
defaultValue string | undefined No
schema TSchema | undefined No
defaultSpans readonly MagicBoxSpan<T>[] | undefined No
onValueChange ((value: string) => void) | undefined No
onExtract MagicBoxExtractor<T, TSchema> Yes
onResult ((spans: readonly MagicBoxSpan<T>[], text: string) => void) | undefined No
onError ((error: Error) => void) | undefined No
offsetUnit OffsetUnit | undefined No
  • rootProps: Native wrapper attributes and events. The component owns its children and state attributes.
  • name: Used as the textarea's native name for host forms. No nested form is created.
  • schema: Passed to the host extractor. Replace its reference to change the extraction target.
  • defaultSpans: Initial annotations for the initial source. Later work goes through onExtract.

MagicBoxController

useMagicBox returns the current source, extraction state, results, and controls. Use canExtract to enable the extraction button.

MagicBoxController<T = unknown>

Field Type Required
value string Yes
status MagicBoxStatus Yes
spans readonly MagicBoxSpan<T>[] Yes
selectedSpan MagicBoxSpan<T> | null Yes
error Error | null Yes
canExtract boolean Yes
setValue (value: string) => void Yes
extract () => Promise<void> Yes
cancel () => void Yes
edit () => void Yes
clear () => void Yes
select (id: string) => void Yes

MagicBoxSpan

Each span links an extracted field to its source text. Use text.slice(start, end) to read the original value. See Source spans for offset validation and Unicode handling.

MagicBoxSpan<T = unknown>

Field Type Required
id string Yes
label string Yes
start number Yes
end number Yes
value T No
confidence number | null No
tone "ember" | "sage" | "sky" | "lilac" No

Search documentation

Type to search the documentation.