OptionalallowOptionalallowAllow a comma-separated multi-range reference — typed or picked (Ctrl+click on the grid appends).
Default false (single range; a pick replaces). Named to match the picker tier's allowMulti
(useSelectionPointer / RangesPickerLayer) — it rides the bus state to gate the grid gesture.
A 'formula' field defaults to true and gates only the pick: false makes Ctrl+click replace
rather than add a reference, while a typed expression may still hold any number of them.
OptionalchangeThe field's CHANGE MODEL. Default 'live'. Beyond suppressing the live onChange (parsing
still runs — error state, picker sync), 'done' makes Enter the FIELD's commit point rather than
a key the host form sees (the shared policy — see useEditCommit) — plus one grammar-specific
effect here: a 'done' reference field drops to caret-edit while the user TYPES (a pick re-arms),
where a 'live' one points for its whole engagement (the RefEdit contract).
OptionaldisabledDisabled: never engages the bus; the text is read-only at the host's discretion.
OptionalequalsLeading-= policy ('formula' grammar only). Default 'optional'.
OptionalhomeThe field's HOME anchor — the coords (with scope) a bare reference (A1) resolves against and
serializes bare for. A host that HAS an anchor (a table's sheet, a conditional-format rule's
cell, the cell an inserted function lands in) should pass it.
BOTH grammars honor it, and in both a field with NO home has no bare form at all: its text stays
fully qualified, and a pick made on the visible tab still carries that tab's name. That is what a
host with no sheet of its own means — a defined name's refers-to is read from wherever the name is
USED, so a bare address left in it names nothing once the field is gone. (Resolving text the user
TYPED still falls back to the selected sheet; there is no other sheet a bare A1 could mean.)
With a home, references on that sheet read bare and only cross-sheet ones carry a sheet name. Only
scope matters to a 'reference' field; the cell coords additionally anchor a 'formula' field's
relative references.
OptionalonLive change notification — fires on every VALID text state (typed or picked), null for cleared.
Invalid in-progress text sets FormulaInputApi.error instead and does not fire.
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 at save):
onChange 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 with the final parsed value at each commit point — a done key
(Enter/Tab/Escape, from the field or the GRID), the explicit FormulaInputApi.commit
(the adornment ✓ / a dialog's OK), or blur to another field. Picker gestures do NOT commit —
drags update only the text; the user finishes explicitly. 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 NEW reference lands as when the picker writes one — 'absolute' ($A$1:$B$2) or
'relative' (A1:B2). Default 'relative', the cell editor's behavior (a formula that is copied
should move with it).
Scoped deliberately narrowly — it decides ONLY the references a pick CREATES:
$ flags, including partial ones ($A1, A$1:B$9). A pick
moves where a reference points; it does not restyle it.$ on the caret's reference.'absolute' is the defined name shape — a name denotes a fixed region, not one relative to
whoever reads it — and the table-resize shape (Excel's $A$3:$D$9).
OptionalpickWhether a pick that is exactly a dynamic array's spill writes the anchor plus # (D2#) instead
of its address. Default false.
D2# follows the spill as it grows or shrinks; D2:E4 stays the extent it was picked at. The
formula bar and in-grid editor always write #; Excel's range fields (conditional formatting,
defined names, dialogs) do not, which is the default here. A name defined over the same extent
does not win here the way it does in the cell editor — fields never write names for a pick. A
single cell, an array-entered block and a blocked spill always write an address. The $ style
follows pickAs and re-scoping as for an address, on the anchor ($D$2#).
OptionalrequiredWhether the field must hold a value. Default false: empty text is the CLEARED value (null),
emitted and committed like any other.
true makes empty text an ERROR instead, so it can never be committed — for a host whose
model has no empty state (the ranges an item is anchored to). A field that MOUNTS empty shows
no error until it is edited.
The committed value. Display text re-derives whenever it changes (see the serialization policy
per grammar). ICellRanges and string are accepted for DX — a host holding ranges (a
table's range, a sheet selection) passes them straight in — and the emitted values are still
ICalculation.IFormula.
A ranges value is addressed by the SDK, never re-serialized here. With a home the address
is localized to it (bare there, qualified elsewhere); WITHOUT one the value's own scoping decides
what the field shows — a SHEET-scoped set reads bare ($B$2:$D$5), a WORKBOOK-scoped one
sheet-qualified (Sheet1!$B$2:$D$5). See ICellRanges.getAddress.
Treat as an IMMUTABLE snapshot: pass a new instance (or string) to change the field; mutating a
held IFormula / ICellRanges in place is not observed.
OptionalworkbookResolution context. Defaults to the enclosing WorkbookContext.
Whether references may reach OTHER sheets. Default
true. The sheet-count gate, sibling to allowMulti's range-count gate — both are declared by the producer because both are properties of what is being picked, and both ride the bus to gate the grid gesture.falseconfines the field to ONE sheet — home's (falling back to the selected sheet when there is no home, which is why a confined field should always pass one):Sheet2!A1) is an ERROR, not a value;ReferenceModeState.scope);Excel's single-sheet inputs are exactly this shape: a table's range, conditional formatting's "Applies to" (multi-range but one sheet —
allowMultiand this are independent). Leave ittruefor anything that genuinely spans sheets, e.g. chart series.