OptionalallowOptionalallowAllow a comma-separated multi-range reference (typed, or Ctrl+click-picked). Default false;
a 'formula' field defaults to true and gates only the pick. See UseFormulaInputOptions.allowMulti.
OptionalapiThe headless field API, for host-driven commit points the blur heuristic can't see — a dialog's
OK handler calls apiRef.current?.commit() (Cancel: .cancel()).
OptionalargumentThe call argument this field's whole text is — the Function Arguments form's rows. An empty field then offers, in its hint popup, the values the parameter is limited to.
OptionalchangeThe field's CHANGE MODEL. Default 'live'.
'done' does three things, not one:
'live' mode Enter bubbles, since every change already applied);'reference' grammar; a pick re-arms) —
a 'live' field points for its whole engagement, the Excel RefEdit contract.A host that acts only on the commit channel should say so here rather than merely leaving onChangeInput unwired — the two look the same to the host but differ at the keyboard.
Independent of the modal ✓/✗ adornments, which follow onDone — the commit channel is what gives them something to do.
OptionalclassClass(es) for the INNER <input> — className styles the FormControl root, which selectors
aimed at the input (a dialog's autoFocusSel) can't use. The dialogs' autofocus convention is
the main use: pass 'autoFocus' and the host's .autoFocus selector finds this field.
OPT-IN, unlike InputField (which always tags its input): a dialog holding both field kinds
decides which one takes first focus by tagging it, rather than by DOM order.
OptionalequalsLeading-= policy ('formula' grammar only). Default 'optional'.
OptionalformIf provided will be registered with react-hook-form.
OptionalformReact-hook-form options.
OptionalgrammarThe field's grammar. 'formula' (default) accepts any expression (=SUM(A1:A5)*2);
'reference' is the "limit input" specialization — a pure reference list
(Sheet1!A1:B2, Sheet2!C1), rejecting function calls and computed references per
ICalculation.IFormula.isReferenceOnly (Excel's RefEdit contract).
OptionalhelperGuidance shown under the field while it is VALID. The error takes that line when there is one — the field reserves it either way, so the layout never shifts.
Without this a host had to render its own caption below the field, on top of the reserved line (which then hid the error).
null (explicitly — not undefined, which takes the reserved default) COLLAPSES the line
instead: the field's block ends at the input. For a form of many fields that shows its messages
somewhere else, ~24px per field of reserved emptiness is most of the page. Pair it with
showError false — otherwise an error still claims a line, and the layout shifts as it
appears — and note that an 'above' label then leaves the block ASYMMETRIC (see
FORMULA_FIELD_ABOVE_LABEL_HEIGHT).
OptionalhideHide the adornment cluster (✓/✗ while engaged in modal mode; the select-current action).
OptionalhomeThe field's HOME anchor — the coords (with scope) a bare reference (A1) resolves against and
serializes bare for. BOTH grammars honor it; a field with no home (either grammar) has no bare
form and stays fully qualified, picks included — the visible tab does not stand in for one.
OptionallabelField label. Default "Formula" ('reference' grammar: "Range").
null (explicitly — not undefined, which takes the default) renders NO label, and the
input's text re-centers in its box (the asymmetric padding only exists to clear the label on
the border). For a field composed into a row whose meaning the row already states — pair with
helperText: null for a fully compact field that centers against its siblings.
OptionallabelWhere the label goes.
'above' puts it on its own line above the field, sized to match the helper/error line BELOW
the field. That symmetry is the point: it leaves the input at the vertical middle of the whole
field block, so a host can vertically center something beside it (a per-argument evaluated
value) and have it line up with the text in the field — without measuring anything, and without
moving when an error appears.
OptionalonThe parse error CHANGED — the message key, or null when the text became valid again.
The error as the field would show it: held back while an operand is expected at the caret
(=A1+, a lone =), and reported when the field is left that way.
A message KEY, not a sentence (the same rule as disabledReasons): the error is state that
outlives a language switch, so the chrome that renders it translates at display — t(key), which
passes a non-key through unchanged.
OptionalonLive notification of the value change — fires on every VALID text state (typed or picked); invalid in-progress text shows the error state instead.
A PREVIEW channel: hosts that mutate the model per change (resize a table, re-source a chart) should act on onDone instead and treat this as optional live feedback.
OptionalonThe raw TEXT channel: every display-text change the user causes (typed, picked, F4'd, reverted) — INVALID states included, and regardless of changeOn.
For hosts that persist authored TEXT rather than a parsed value (a name's "refers to", written through to a draft that validates on save): onChangeInput would leave them holding the last VALID text while the field shows something else. An outside value change does not fire it.
OptionalonThe COMMIT channel: fires once with the final parsed value when the edit finishes — a done key
(Enter/Tab/Escape, from the field or the grid), the adornment toggle-off, or blur to another
field. args.reason distinguishes accept from cancel (a cancel delivers the reverted session
baseline). Not fired on an accept while the text is invalid — the error stays shown instead.
OptionalpickWhat a PICK writes — 'absolute' ($A$1:$B$2) or 'relative' (A1:B2). Default 'relative'
(the cell editor's behavior). A DEFAULT, not a constraint: typing and F4 still reach either form,
and a value handed in keeps the fixability it came with. 'absolute' is the defined-name and
table-resize shape. See UseFormulaInputOptions.pickAs.
OptionalpickWhether a pick that is exactly a dynamic array's spill writes D2# instead of its address.
Default false, as Excel's range fields; the cell editor always does. See
UseFormulaInputOptions.pickSpills.
OptionalplaceholderPlaceholder. Default "Enter Formula" ('reference' grammar: "Enter Range").
OptionalrefReference to the element.
OptionalrequiredWhether the field must hold a value. Default false: empty text is the cleared value (null).
true makes empty text an error, so it is never committed — see
UseFormulaInputOptions.required.
OptionalshowShow the parse error under the field.
false keeps the error OUTLINE (the field still reads as wrong) but leaves the helper line to
helperText — for a host that collects errors through onChangeError and shows
them somewhere of its own: one message area for a form of many fields, rather than a line under
each.
OptionalvalidationAn error the host found in text that PARSES — a list item holding the separator. Outlines the field and takes the helper line as a parse error does; a parse error wins when there are both. A message key or plain text, as onChangeError's.
The committed value. The display text re-derives whenever it changes (per the grammar's
serialization policy). Accepted as IFormula | ICellRanges | string for DX — a host holding
ranges passes them straight in. With a home the address is localized to it (bare there,
qualified elsewhere); without one the ranges' own scoping is what the field shows (sheet-scoped
read bare, workbook-scoped sheet-qualified; see ICellRanges.getAddress). The change channels
always emit IFormula — read ranges via value.getReferences() or apiRef.current.getRanges().
OptionalworkbookResolution/picking context. Defaults to the enclosing WorkbookContext.
Whether references may reach other sheets. Default
true. Setfalsefor a single-sheet input (a table's range, conditional formatting's "Applies to"): typed cross-sheet references become errors, the grid refuses picks on other sheets, and addresses display bare. Independent of allowMulti — seeUseFormulaInputOptions.allowCrossSheet.