Skip to main content
Decorators are tappable indicators (icon + label) attached to a field, column, row, or cell. Taps are delivered through onFocus so your app can run custom logic — navigation, uploads, etc.

​
Decorator model

val decorator = Decorator().apply {
    action = "openHelp"     // optional in Kotlin, unique within scope when set
    icon   = "circle-info"  // optional, see Supported icons
    label  = "Help"         // optional
    color  = "#3B82F6"      // optional, must be #RRGGBB
}
PropertyTypeDescription
actionString?Non-empty and unique among decorators at the same path.
iconString?Icon name (see Supported icons).
labelString?Text shown next to or instead of the icon.
colorString?6-digit hex color: #RRGGBB (e.g. #3B82F6).
The control is shown only when there is a non-empty icon or label (isDisplayable). Action-only entries are stored but not displayed.

​
Constructing a path

DocumentEditor resolves decorators using a slash-separated path. Every path starts with pageId/fieldPositionId. What you append after that determines what gets decorated.
Reserved keywords. The path grammar uses three reserved tokens — schemas, rows, and columns. Anything else in a path slot is treated as an id (page id, field-position id, row id, column id, or schema key). Don’t use these keywords as ids.

​
Field decorators

Just the two ids. Applies to the field’s header. 
val fieldPath = "$pageId/$fieldPositionId"

​
Table — /rows, /columns/colId, or specific rowId / rowId/colId

A table has four decorator scopes, two common (defaults applied everywhere) and two specific (overrides for one row or cell):
What you wantAppendExample
Common decorators on every row/rowspageId/fpId/rows
Decorators on one specific row/rowIdpageId/fpId/row_42
Common decorators on every cell in a column/columns/colIdpageId/fpId/columns/col_status
Decorators on one specific cell/rowId/colIdpageId/fpId/row_42/col_status
Specific paths inherit from the matching common path on the first write — anything you set on /rows shows on row_42 until you write to row_42 directly.

​
Collection — same as table, plus /schemas/schemaKey/… for nested rows

A collection’s root rows behave like a table — the four scopes above use the exact same path shapes. Take a “People” collection where each person row holds a nested “Addresses” schema: 
schema "people"     (root, children: [addresses])
schema "addresses"  (nested under people)

Rows:
  p_alice                                  ← row in "people"
    addresses → [ addr_home, addr_work ]   ← rows in "addresses", under p_alice
  p_bob
    addresses → [ addr_apt ]
Common rows / columns of any schema — root or nested — are schema-level defaults. Address them directly with schemas/schemaKey/…, no parent walk needed:
What you wantPath shapeExample
Common rows in any schemapageId/fpId/schemas/sk/rowspageId/fpId/schemas/addresses/rows
Common columns in any schemapageId/fpId/schemas/sk/columns/colIdpageId/fpId/schemas/addresses/columns/col_zip
A specific nested row or cell lives under a particular parent. Walk through that parent’s row id, then schemas/sk/, then the nested row id:
What you wantPath shapeExample
Specific nested row…/rowId/schemas/sk/nestedRowIdpageId/fpId/p_alice/schemas/addresses/addr_home
Specific nested cell…/rowId/schemas/sk/nestedRowId/colIdpageId/fpId/p_alice/schemas/addresses/addr_home/col_zip
If addresses itself had children, you’d chain another schemas/.../rowId/… after addr_home — the same pattern repeats for every level.
Schema keys come from the field’s schema map. The schema marked root: true holds top-level rows; its children array names the nested schemas reachable from a row in this schema.

​
API

Four methods, all on documentEditor.decorators. Errors are reported via onError as JoyfillError.DecoratorError(DecoratorError). 
val fieldPath = "$pageId/$fieldPositionId"

documentEditor.decorators.get(fieldPath)                          // -> List<Decorator>
documentEditor.decorators.add(fieldPath, decorator)
documentEditor.decorators.update(fieldPath, action = "openHelp", decorator = updated)
documentEditor.decorators.remove(fieldPath, action = "openHelp")
Same shape for every path scope. A few examples: 
// Common row decorators on a table — applied to every row
documentEditor.decorators.add("$pageId/$fpId/rows", duplicate)

// Override on a specific row
documentEditor.decorators.add("$pageId/$fpId/$rowId", archive)

// Cell-specific decorator
documentEditor.decorators.add("$pageId/$fpId/$rowId/$colId", upload)

// Nested collection row
val nestedPath = "$pageId/$fpId/$parentRowId/schemas/$nestedSK/$nestedRowId"
documentEditor.decorators.add(nestedPath, comment)

​
Behavior to know

  • Copy-on-write seed. First write to a row-self / cell scope seeds from the matching common scope, so existing common decorators stay visible on that row alongside your override. Subsequent writes diverge freely.
  • Collection license gating. Writes against a collection field require a license that enables collection features. Without it, the call emits decoratorError and is rejected.

​
Handling taps

Decorator taps come through onFocus with the decorator’s action exposed on the field event’s type / target. rowIds / columnId / parentPath on FieldIdentifier tell you where the user tapped. 
onFocus = { event ->
    val field = event.fieldEvent ?: return@onFocus

    val action = field.type
    if (!action.isNullOrEmpty()) {
        // Decorator tap
        println("Decorator: $action, field: ${field.fieldID}, rows: ${field.rowIds ?: []}, column: ${field.columnId ?: "-"}")
    } else {
        // Ordinary field focus
    }
}
See Event handling for the full focus/blur flow.

​
Errors

All four APIs report through onError as JoyfillError.DecoratorError(DecoratorError):
  • Path didn’t resolve (bad ids, deleted row, malformed grammar)
  • Validation (action empty, color not #RRGGBB)
  • Duplicate action in batch or against an existing entry
  • remove / update with an unknown action
  • Collection write without a valid license
Reads (get) on an unresolvable path also emit onError and return [].

​
Display limits

DecoratorConfig, passed to DocumentEditor at init, controls how many decorators render inline before the rest collapse into a kebab menu. 
val config = DecoratorConfig(
    visibleLimitInFields = 2,   // field + column scopes; default 2
    visibleLimitInRows = 1      // row scopes; default 1
)
val editor = DocumentEditor(document = doc, decoratorConfig = config)

​
Supported icons

The SDK maps common names to bundled artwork, including: camera, import, paperclip, image, file, comment, comments, upload, download, rotate, cloud, filter, share, paper-plane, folder, folder-open, magnet, eye, circle-info, add, plus, print, flag. Unknown names fall back to a default symbol.