Input blocks

Take a value from the person: text, numbers, dates, choices, files. They output the value they hold and fire an event when it is committed.

This page is generated from the block registry, so it lists exactly what the Page Designer accepts. 53 blocks.

Block	What it is for
core.account-lookup	Dropdown to choose a ledger account; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.address-input	Input for a postal address held as one value.
core.autocomplete	A typeahead text-entry-plus-suggestions control — for pickers where the option list may be large or server-sourced and the user should be able to type to filter (reporting manager search, job title search), optionally also allowing free text that matches no offered option.
core.barcode-scan-input	Text input that accepts a typed or scanned barcode; fires committed.
core.branch-selector	Dropdown to choose a branch; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.checkbox	A boolean toggle field, renderable either as a traditional checkbox or as a switch — for flags like "Is Active", "Enable notifications", "Remote eligible".
core.checkbox-group	Group of checkboxes that outputs the list of ticked values; fires committed.
core.checkout-form	Checkout form for a website store; fires submitted.
core.city-select	Dropdown to choose a city; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.code-editor	An editable source-code text area with a language hint.
core.collection-controls	Search box, sort choices and filters for a collection of items.
core.color-picker	A color-value entry field — for tag colors, calendar category colors, theme accent selection, or any hex-color-valued setting.
core.cost-center-lookup	Dropdown to choose a cost centre; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.country-select	Dropdown to choose a country; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.currency-input	A money-amount entry field with locale/currency-aware display formatting — for salary, bonus, expense amounts, and any monetary value.
core.currency-selector	Dropdown to choose a currency; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.current-location-button	Button that reads the device's location; fires locationCaptured or locationError.
core.dashboard-date-filter	Date or period selector for a dashboard; outputs the value and fires committed.
core.date-picker	A single-date entry field — for joining date, date of birth, effective date, or any calendar-date-only value (no time component).
core.date-range-picker	Picker for a start and end date; outputs the range and fires committed.
core.datetime-picker	A combined date-and-time entry field — for interview schedules, meeting start times, or any single-instant business value where splitting date and time across two widgets would fragment one logical field.
core.department-selector	Dropdown to choose a department; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.document-upload	Document uploader with optional multiple files, target cabinet and accepted types.
core.file-upload	Lets a user attach one or more files (documents, images, resumes, receipts) to a form or record via drag-and-drop or a file picker.
core.image-upload	Image uploader with optional multiple files, target cabinet, accepted types and camera capture; outputs the uploaded file reference.
core.language-selector	Dropdown to choose a language; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.lookup	A related-record picker — framed explicitly as "select's option contract + the async OptionsDataSource seam, framed as a related-record picker" (as opposed to core.select's plain choice-list framing).
core.markdown-editor	An editable markdown text area (distinct from core.markdown-viewer, which is read-only).
core.member-account	Account area for a website member, with sign-in, optional registration and order history.
core.mention-input	Text input that lets the person @mention people from a data source.
core.multi-select	A closed-choice, multiple-selection control — for fields where more than one option can apply simultaneously (skills, certifications, languages spoken, assigned roles).
core.number-input	A locale-correct numeric entry field (originally shipped as W4-09) — for counts, quantities, ages, years-of-experience, and any plain numeric value that isn't a currency amount (see core.currency-input for money).
core.numeric-keypad	On-screen numeric keypad, optionally with decimals and a length limit; fires valueChanged and committed.
core.organization-selector	Dropdown to choose an organisation; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.path	Step path (such as a sales stage bar) showing options in order with the current one highlighted; linear controls whether steps must be taken in order.
core.people-picker	Picker for selecting several people from a data source; outputs the chosen values.
core.permission-picker	Picker for choosing permissions or roles from a list of role options.
core.project-lookup	Dropdown to choose a project; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.radio-group	A mutually-exclusive, always-visible choice control — for small, fixed option sets where every choice should be visible at once (employment type, gender, yes/no-style questions with more than two options), rather than hidden behind a dropdown.
core.rating	Capture (or display) a star-style rating value, with a configurable maximum and an optional read-only mode.
core.rich-text	An editable rich-text (formatted HTML) input for long-form authored content — job descriptions, performance review notes, announcement bodies — anywhere plain text isn't expressive enough.
core.select	A closed-choice dropdown — the standard picker for a fixed or server-sourced option list (department, status, employment type) where the committed value must be one of the offered options.
core.signature-pad	Captures a handwritten signature (or initials/mark) as a drawn stroke and commits it as a signed image, for use cases like offer-letter acceptance, delivery proof-of-receipt, or approval sign-off.
core.site-search	Search box for a website; outputs the query and shows results up to a limit.
core.slider	A drag-to-select numeric range control — for bounded scalar values like a performance rating, satisfaction score, or completion percentage, where a visual range is more usable than typing a number.
core.state-select	Dropdown to choose a state or region; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.tax-code-lookup	Dropdown to choose a tax code; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.
core.text-input	A single-line text field by default — or a plain-text textarea when multiline: true — the general-purpose free-text input every Form uses for names, codes, short descriptions, longer plain-text fields (Reason, Comments, Notes), and (via secret) password/PIN entry.
core.time-picker	A time-only entry field (no date component) — for shift start/end time, attendance punch time, or any wall-clock value.
core.time-slot-picker	Picker for one of a set of time slots; fires committed.
core.toggle-button	An exclusive-choice input control rendered as a row of toggle buttons — a render variant of the same option-list contract core.select uses, for when the choices should look like pressable buttons rather than a dropdown.
core.tree-select	A hierarchical single-value picker — for selecting one node out of a nested structure (org unit, category tree, geographic region) where the options themselves have a parent/child shape rather than a flat list.
core.warehouse-lookup	Dropdown to choose a warehouse; options are fixed or come from a data source (optionsSourceKey); outputs the chosen value and fires committed.

core.account-lookup

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.address-input

Property	Type	Set from	Default
value	json	static, binding

Events: committed

Outputs: value (json)

core.autocomplete

A typeahead text-entry-plus-suggestions control — for pickers where the option list may be large or server-sourced and the user should be able to type to filter (reporting manager search, job title search), optionally also allowing free text that matches no offered option. Designer palette icon: manage-search.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
freeSolo	boolean	static	false
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-reporting-manager",
  "blockType": "core.autocomplete",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.reportingManager.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "reportingManagerId" } },
    "freeSolo": { "source": "static", "value": false }
  }
}

• Set freeSolo: true only when an unmatched value is genuinely a valid
• Prefer this over core.select whenever the option set is large enough
• Since there's no built-in membership validation even in non-freeSolo

core.barcode-scan-input

Property	Type	Set from	Default
value	string	static, binding

Events: committed

Outputs: value (string)

core.branch-selector

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.checkbox

A boolean toggle field, renderable either as a traditional checkbox or as a switch — for flags like "Is Active", "Enable notifications", "Remote eligible". Designer palette icon: check-box.

Property	Type	Set from	Default
checked	boolean	static, binding
variant	string	static	checkbox

Events: committed

Outputs: checked (boolean)

{
  "contractVersion": 1,
  "instanceId": "employee-is-active",
  "blockType": "core.checkbox",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.isActive.label",
  "properties": {
    "checked": { "source": "binding", "binding": { "scope": "form", "key": "isActive" } }
  }
}

• Use variant: "switch" for immediate-effect settings (notifications,
• Since commit always toggles rather than accepting an explicit value,
• Give every checkbox a real a11yLabelKey — the definition-level i18n

core.checkbox-group

Property	Type	Set from	Default
values	json	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...

Events: committed

Outputs: values (json)

core.checkout-form

Property	Type	Set from	Default
title	string	static	Checkout

Events: submitted

core.city-select

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.code-editor

An editable source-code text area with a language hint.

Property	Type	Set from	Default
value	string	static, binding	function greet(name) { return `Hello, ${name}...
language	string	static	plaintext
minHeight	string	static	200px

Events: committed

Outputs: value (string)

{ "blockType": "core.code-editor", "instanceId": "expression-editor", "blockVersion": "1.0.0", "contractVersion": 1,
  "properties": { "value": {"source":"binding","binding":{"scope":"form","key":"script"}}, "language": {"source":"static","value":"javascript"} } }

• Set language accurately for readable syntax highlighting.

core.collection-controls

Property	Type	Set from	Default
showSearch	boolean	static	true
sortOptions	json	static	[{"label":"Name A–Z","field":"title","order":"a...
filters	json	static	[]

core.color-picker

A color-value entry field — for tag colors, calendar category colors, theme accent selection, or any hex-color-valued setting. Designer palette icon: palette.

Property	Type	Set from	Default
value	string	static, binding	#3b82f6

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "leave-category-color",
  "blockType": "core.color-picker",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.leaveCategory.color.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "categoryColor" } }
  }
}

• Since there is no hex-format validation, add a Form-level pattern rule
• Use this widget for genuinely free-form color choice; for a constrained
• Keep the default "#3b82f6" in mind — an unbound/unset instance is

core.cost-center-lookup

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.country-select

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.currency-input

A money-amount entry field with locale/currency-aware display formatting — for salary, bonus, expense amounts, and any monetary value. Introduced as part of the taxonomy v2 pass, framed explicitly as "a number presentation variant" — ADR 0005's underlying numeric semantics are unchanged. Designer palette icon: payments.

Property	Type	Set from	Default
value	number	static, binding
currencyCode	string	static, binding

Events: committed

Outputs: value (number)

{
  "contractVersion": 1,
  "instanceId": "employee-monthly-salary",
  "blockType": "core.currency-input",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.monthlySalary.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "monthlySalary" } },
    "currencyCode": { "source": "static", "value": "USD" }
  }
}

• Always bind (not hardcode as static) currencyCode when a tenant/entity
• Never attempt to store a currency symbol or formatted string as value —
• Since invalid entry silently blocks the commit, ensure the surrounding

core.currency-selector

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.current-location-button

Property	Type	Set from	Default
label	string	static, expression, binding	Use Current Location
hidden	boolean	static, expression, binding	false

Events: locationCaptured, locationError

core.dashboard-date-filter

Property	Type	Set from	Default
value	json	static, binding
mode	string	static	date

Events: committed

Outputs: value (json)

core.date-picker

A single-date entry field — for joining date, date of birth, effective date, or any calendar-date-only value (no time component). Designer palette icon: calendar-month.

Property	Type	Set from	Default
value	date	static, binding
pickerMode	string	static	date

Events: committed

Outputs: value (date)

{
  "contractVersion": 1,
  "instanceId": "employee-joining-date",
  "blockType": "core.date-picker",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.joiningDate.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "joiningDate" } }
  }
}

• Remember the platform-wide convention: date-valued database columns are
• Add explicit Form-level validation for date ranges (e.g. joining date
• Prefer core.datetime-picker instead of pairing this with a separate

core.date-range-picker

Property	Type	Set from	Default
value	json	static, binding
mode	string	static	date

Events: committed

Outputs: value (json)

core.datetime-picker

A combined date-and-time entry field — for interview schedules, meeting start times, or any single-instant business value where splitting date and time across two widgets would fragment one logical field. Introduced in the taxonomy v2 pass. Designer palette icon: event.

Property	Type	Set from	Default
value	string	static, binding

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "interview-scheduled-at",
  "blockType": "core.datetime-picker",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.interview.scheduledAt.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "interviewScheduledAt" } }
  }
}

• Prefer this widget over separate date-picker + time-picker fields
• Remember the platform-wide convention that stored date/time columns are
• Add an explicit "must be in the future" (or similar) Form validation rule

core.department-selector

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.document-upload

Property	Type	Set from	Default
value	json	static, binding
multiple	boolean	static	true
cabinetId	string	static, expression
mode	string	static	dms
accept	string	static	.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.csv

Events: committed

Outputs: value (json)

core.file-upload

Lets a user attach one or more files (documents, images, resumes, receipts) to a form or record via drag-and-drop or a file picker.

Property	Type	Set from	Default
value	json	static, binding
accept	string	static
multiple	boolean	static	true
cabinetId	string	static, expression
mode	string	static	dms
capture	string	static

Events: committed

Outputs: value (json)

{
  "instanceId": "upload-resume",
  "blockType": "core.file-upload",
  "blockVersion": "1.0.0",
  "contractVersion": 1,
  "properties": {
    "accept": { "source": "static", "value": ".pdf,.doc,.docx" },
    "multiple": { "source": "static", "value": false },
    "value": { "source": "binding", "value": { "scope": "form", "key": "resumeFiles" } }
  }
}

• Always set accept to narrow the native picker, but never rely on it alone for security or business-rule enforcement — pair with a real server-side content-type/size check once a FileUploadSource is wired.
• Wire a real FileUploadSource (e.g. against the platform's /api/v1/assets endpoint) before shipping any page that uses this block in production — without it, uploads are a no-op.
• Use multiple: false for single-document fields (e.g. one resume) to keep the UI and validation simpler.

core.image-upload

Property	Type	Set from	Default
value	json	static, binding
multiple	boolean	static	true
cabinetId	string	static, expression
mode	string	static	dms
accept	string	static	image/*
capture	string	static	environment

Events: committed

Outputs: value (json)

core.language-selector

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.lookup

A related-record picker — framed explicitly as "select's option contract + the async OptionsDataSource seam, framed as a related-record picker" (as opposed to core.select's plain choice-list framing). Intended for fields that reference another entity's record, e.g. an employee's manager, a customer on an invoice. Designer palette icon: search.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
recordType	string	static
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-manager-lookup",
  "blockType": "core.lookup",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.manager.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "managerId" } },
    "recordType": { "source": "static", "value": "Employee" }
  }
}

• Don't assume recordType scopes the query automatically — it's still
• Prefer this widget's naming/intent (core.lookup) over core.select
• Add a Form-level "must reference an existing record" validation rule

core.markdown-editor

An editable markdown text area (distinct from core.markdown-viewer, which is read-only).

Property	Type	Set from	Default
value	string	static, binding	# Sample Heading Start typing markdown here.
minHeight	string	static	160px

Events: committed

Outputs: value (string)

{ "blockType": "core.markdown-editor", "instanceId": "notes-editor", "blockVersion": "1.0.0", "contractVersion": 1,
  "properties": { "value": {"source":"binding","binding":{"scope":"form","key":"notes"}} } }

• Pair with core.markdown-viewer to preview the rendered output elsewhere on the same page/form.

core.member-account

Property	Type	Set from	Default
title	string	static	Your account
allowRegister	boolean	static	true
showOrders	boolean	static	true

core.mention-input

Property	Type	Set from	Default
value	string	static, expression, binding
optionsSourceKey	string	static
placeholder	string	static	Type @ to mention someone...

Events: committed

Outputs: value (string), mentions (json)

core.multi-select

A closed-choice, multiple-selection control — for fields where more than one option can apply simultaneously (skills, certifications, languages spoken, assigned roles). Designer palette icon: checklist.

Property	Type	Set from	Default
values	json	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...

Events: committed

Outputs: values (json)

{
  "contractVersion": 1,
  "instanceId": "employee-skills",
  "blockType": "core.multi-select",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.skills.label",
  "properties": {
    "values": { "source": "binding", "binding": { "scope": "form", "key": "skillIds" } },
    "options": {
      "source": "static",
      "value": [
        { "value": "js", "labelKey": "hcm.skill.javascript" },
        { "value": "java", "labelKey": "hcm.skill.java" },
        { "value": "sql", "labelKey": "hcm.skill.sql" }
      ]
    }
  }
}

• Never wire a chain expecting an incremental "toggle one value" event —
• Bind values to an actual array-typed entity field (e.g. a
• Add a Form-level "at least one selected" rule explicitly if the field is

core.number-input

A locale-correct numeric entry field (originally shipped as W4-09) — for counts, quantities, ages, years-of-experience, and any plain numeric value that isn't a currency amount (see core.currency-input for money). Designer palette icon: pin.

Property	Type	Set from	Default
value	number	static, binding
precision	number	static
min	number	static
max	number	static

Events: committed

Outputs: value (number)

{
  "contractVersion": 1,
  "instanceId": "employee-years-experience",
  "blockType": "core.number-input",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.yearsExperience.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "yearsExperience" } },
    "precision": { "source": "static", "value": 0 },
    "min": { "source": "static", "value": 0 },
    "max": { "source": "static", "value": 50 }
  }
}

• Always set precision explicitly for money-adjacent counts (e.g. hours,
• Use core.currency-input instead of this widget plus a manual currency
• Treat min/max as UI hints, not enforcement; add a matching Form

core.numeric-keypad

Property	Type	Set from	Default
value	string	static, binding	0
allowDecimal	boolean	static	true
maxLength	number	static	10
hidden	boolean	static, expression, binding	false

Events: valueChanged, committed

Outputs: value (string)

core.organization-selector

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.path

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...
linear	boolean	static	true

Events: committed

Outputs: value (string)

core.people-picker

Property	Type	Set from	Default
values	json	static, binding
optionsSourceKey	string	static

Events: committed

Outputs: values (json)

core.permission-picker

Property	Type	Set from	Default
values	json	static, binding
roleOptions	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...

Events: committed

Outputs: values (json)

core.project-lookup

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.radio-group

A mutually-exclusive, always-visible choice control — for small, fixed option sets where every choice should be visible at once (employment type, gender, yes/no-style questions with more than two options), rather than hidden behind a dropdown. Designer palette icon: radio-button-checked.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-employment-type",
  "blockType": "core.radio-group",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.employmentType.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "employmentType" } },
    "options": {
      "source": "static",
      "value": [
        { "value": "full-time", "labelKey": "hcm.employmentType.fullTime" },
        { "value": "part-time", "labelKey": "hcm.employmentType.partTime" },
        { "value": "contract", "labelKey": "hcm.employmentType.contract" }
      ]
    }
  }
}

• Reserve this widget for genuinely small option sets (2-6 choices);
• Since there's no async data-source seam, don't try to wire a live query
• Add Form-level required validation explicitly if a choice is mandatory —

core.rating

Capture (or display) a star-style rating value, with a configurable maximum and an optional read-only mode.

Property	Type	Set from	Default
value	number	static, binding	0
max	number	static	5
readOnly	boolean	static	false

Events: committed

Outputs: value (number)

{
  "instanceId": "rating-service-quality",
  "blockType": "core.rating",
  "blockVersion": "1.0.0",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "page", "key": "feedback.serviceRating" } },
    "max": { "source": "static", "value": 5 },
    "readOnly": { "source": "static", "value": false }
  },
  "a11yLabelKey": "feedback.form.serviceRating.label",
  "events": {
    "committed": {
      "source": "action-chain",
      "actions": [{ "type": "state.set", "scope": "page", "key": "feedback.serviceRating", "valueFromEvent": "new" }]
    }
  }
}

• Always author an a11yLabelKey on core.rating instances used as real form inputs — it is the platform's own established convention for giving input-class controls a genuine, visible field label (the i18n labelFrom default is a generic fallback only).
• Set readOnly: true for average/summary display uses (e.g. "4.2 average rating") rather than reusing a display widget for that purpose.
• Bind value (not static-author it) whenever the rating is meant to persist — value's sources are deliberately static/binding only, with no expression source, since a rating is fundamentally a stored/committed value, not a computed display.

core.rich-text

An editable rich-text (formatted HTML) input for long-form authored content — job descriptions, performance review notes, announcement bodies — anywhere plain text isn't expressive enough.

Property	Type	Set from	Default
value	string	static, binding
placeholder	string	static
minHeight	number	static	160

Events: committed

Outputs: value (string)

{
  "instanceId": "rtf-job-description",
  "blockType": "core.rich-text",
  "blockVersion": "1.0.0",
  "contractVersion": 1,
  "properties": {
    "value": { "source": "binding", "value": { "scope": "form", "key": "jobDescription" } },
    "placeholder": { "source": "static", "value": "Describe responsibilities, requirements, and benefits..." },
    "minHeight": { "source": "static", "value": 240 }
  }
}

• Treat value as HTML — any consumer that redisplays it (a viewer, a PDF export) can trust it was already sanitized, but should still avoid dangerouslySetInnerHTML-style shortcuts of its own without review.
• Use minHeight to reserve enough vertical space for typical content length, avoiding layout jump as the author types.
• Prefer this over core.text-input (including its multiline: true textarea mode, ai/widgets/text-input.md) only when formatting (bold/lists/links) is genuinely needed — a plain multiline field is lighter weight and doesn't carry HTML sanitization overhead.

core.select

A closed-choice dropdown — the standard picker for a fixed or server-sourced option list (department, status, employment type) where the committed value must be one of the offered options. Designer palette icon: arrow-drop-down-circle.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-department",
  "blockType": "core.select",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.department.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "departmentId" } },
    "options": {
      "source": "static",
      "value": [
        { "value": "eng", "labelKey": "hcm.department.engineering" },
        { "value": "hr", "labelKey": "hcm.department.humanResources" },
        { "value": "fin", "labelKey": "hcm.department.finance" }
      ]
    }
  }
}

• Use static options (or a page-loader-populated binding) for small,
• optionsSourceKey disambiguates per FIELD now (2026-08-17) — it's safe
• Remember commit performs no membership validation — pair with a Form

core.signature-pad

Captures a handwritten signature (or initials/mark) as a drawn stroke and commits it as a signed image, for use cases like offer-letter acceptance, delivery proof-of-receipt, or approval sign-off.

Property	Type	Set from	Default
value	string	static, binding
strokeColor	string	static	#1a1a1a
backgroundColor	string	static	#ffffff

Events: committed

Outputs: value (string)

{
  "instanceId": "sig-offer-acceptance",
  "blockType": "core.signature-pad",
  "blockVersion": "1.0.0",
  "contractVersion": 1,
  "properties": {
    "strokeColor": { "source": "static", "value": "#0b3d91" },
    "backgroundColor": { "source": "static", "value": "#ffffff" },
    "value": { "source": "binding", "value": { "scope": "form", "key": "candidateSignature" } }
  }
}

• Bind value to a form or entity field of a text/blob type — the committed value is a base64 data URI, not a file reference.
• Use clear before requesting a fresh signature so a stale value never persists into a resubmission.
• Pair with a "required" validation rule if a signature is mandatory — the block itself does not enforce that a stroke was drawn.

core.site-search

Property	Type	Set from	Default
placeholder	string	static	Search the site
limit	number	static	8

core.slider

A drag-to-select numeric range control — for bounded scalar values like a performance rating, satisfaction score, or completion percentage, where a visual range is more usable than typing a number. Designer palette icon: tune.

Property	Type	Set from	Default
value	number	static, binding	0
min	number	static	0
max	number	static	100
step	number	static	1

Events: committed

Outputs: value (number)

{
  "contractVersion": 1,
  "instanceId": "performance-review-rating",
  "blockType": "core.slider",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.performanceReview.rating.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "overallRating" } },
    "min": { "source": "static", "value": 0 },
    "max": { "source": "static", "value": 100 },
    "step": { "source": "static", "value": 5 }
  }
}

• Always set min/max/step explicitly rather than relying on the
• Because out-of-range or non-numeric commits are silently absorbed rather
• Pair with a visible numeric readout (e.g. a core.label bound to the

core.state-select

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.tax-code-lookup

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)

core.text-input

A single-line text field by default — or a plain-text textarea when multiline: true — the general-purpose free-text input every Form uses for names, codes, short descriptions, longer plain-text fields (Reason, Comments, Notes), and (via secret) password/PIN entry. Designer palette icon: input. Multiline vs. core.rich-text. Set multiline: true (+ optional rows, default 4) for a plain-text field that should wrap across lines but never needs formatting — this renders as a real <textarea> on web (MUI's own multiline/rows passthrough) and a growing multi-line TextInput on native. Reach for core.rich-text (ai/widgets/rich-text.md) instead only when the field genuinely needs bold/lists/links — its value is sanitized HTML, real markup, not plain text; don't use it just to get line-wrapping.

Property	Type	Set from	Default
value	string	static, binding
placeholder	string	static, expression
maxLength	number	static
secret	boolean	static	false
revealToggle	boolean	static	false
icon	string	static
iconVariant	string	static	plain
htmlAttributes	json	static
multiline	boolean	static	false
rows	number	static	4
inputType	string	static	text
mask	string	static

Events: committed, focus, blur

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-full-name",
  "blockType": "core.text-input",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.fullName.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "fullName" } },
    "placeholder": { "source": "static", "value": "Enter full legal name" },
    "maxLength": { "source": "static", "value": 120 }
  }
}

• Use binding (not static) for the value source whenever the field is
• Prefer secret + revealToggle together for password/PIN fields rather
• Don't rely on maxLength alone for data integrity; pair it with a Form

core.time-picker

A time-only entry field (no date component) — for shift start/end time, attendance punch time, or any wall-clock value. Introduced in the taxonomy v2 UI-designer audit pass (2026-07-16). Designer palette icon: schedule.

Property	Type	Set from	Default
value	string	static, binding

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "shift-start-time",
  "blockType": "core.time-picker",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.shift.startTime.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "shiftStartTime" } }
  }
}

• Since the wire format ("HH:mm") is not enforced by the widget, validate
• Use two core.time-picker instances (start/end) for shift or slot
• Pair with core.select for timezone when the value must be

core.time-slot-picker

Property	Type	Set from	Default
slots	json	static, expression, binding	[{"value":"09:00","label":"9:00 AM","available"...
value	string	static, binding

Events: committed

Outputs: value (string)

core.toggle-button

An exclusive-choice input control rendered as a row of toggle buttons — a render variant of the same option-list contract core.select uses, for when the choices should look like pressable buttons rather than a dropdown.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding	[{"value":"option-1","labelKey":"core.sampleOpt...

Events: committed

Outputs: value (string)

{
  "instanceId": "toggle-employment-type",
  "blockType": "core.toggle-button",
  "blockVersion": "1.0.0",
  "contractVersion": 1,
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "employmentType" } },
    "options": {
      "source": "static",
      "value": [
        { "value": "full-time", "labelKey": "hcm.employmentType.fullTime" },
        { "value": "part-time", "labelKey": "hcm.employmentType.partTime" },
        { "value": "contract", "labelKey": "hcm.employmentType.contract" }
      ]
    }
  }
}

• Use for a small, exclusive option set where a button-row visual reads better than a dropdown (e.g. AM/PM, employment type).
• Prefer core.button-group instead when there is no field value to persist — toggle-button is for bound input, button-group is for one-shot actions.
• Bind value (not static) whenever the selection must round-trip with a Form/entity field.

core.tree-select

A hierarchical single-value picker — for selecting one node out of a nested structure (org unit, category tree, geographic region) where the options themselves have a parent/child shape rather than a flat list. Introduced as "select's option contract, hierarchically nested." Designer palette icon: account-tree.

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding

Events: committed

Outputs: value (string)

{
  "contractVersion": 1,
  "instanceId": "employee-org-unit",
  "blockType": "core.tree-select",
  "blockVersion": "1.0.0",
  "a11yLabelKey": "hcm.employee.orgUnit.label",
  "properties": {
    "value": { "source": "binding", "binding": { "scope": "form", "key": "orgUnitId" } },
    "options": {
      "source": "static",
      "value": [
        {
          "value": "co-1",
          "labelKey": "hcm.orgUnit.acmeCorp",
          "children": [
            { "value": "br-1", "labelKey": "hcm.orgUnit.northAmerica" },
            { "value": "br-2", "labelKey": "hcm.orgUnit.emea" }
          ]
        }
      ]
    }
  }
}

• Because there's no live-query seam, pre-fetch the nested tree via a
• Keep value and TreeSelectOption.value types consistent (both
• Add a Form-level "must resolve to a real node" validation rule

core.warehouse-lookup

Property	Type	Set from	Default
value	string	static, binding
options	json	static, expression, binding
optionsSourceKey	string	static

Events: committed

Outputs: value (string)