Fields
Fields are how your tool exchanges data with the user. They're declared in artifuncs.json under fields.input, fields.output, and settings. Each field has a type plus optional options.
Common options
These apply to every field type unless noted:
| Option | Type | Description |
|---|---|---|
label | string | Human-readable label shown above the field. Defaults to the field name. |
subtext | string | Small helper text shown under the label. |
topRightHint | string | Small muted hint pinned to the top-right of the label row (e.g. "png, jpg, webp"). Good for format/limit reminders. |
placeholder | string | Placeholder text inside empty inputs (text-like fields only). |
default | any | Initial value. Type must match the field. |
readonly | boolean | User can read but not edit. Used for outputs. |
disabled | boolean | Field is greyed out and inert. |
copiable | boolean | Shows a copy-to-clipboard button. Useful on outputs. |
clearable | boolean | Shows a clear (×) button to wipe the value. |
subtext vs topRightHint: subtext is helper text near the field; topRightHint is a compact reminder pinned to the right edge of the label row — ideal for accepted formats or limits.
"avatar": {
"type": "file",
"label": "Source image",
"topRightHint": "png, jpg, webp",
"accept": "image/*"
}
text-field
Single-line text.
"name": {
"type": "text-field",
"label": "Your name",
"placeholder": "Ada Lovelace",
"default": ""
}
password
Single-line text that's masked as you type — same options as text-field. An eye button sits inside the field on the right; hold it down to reveal the value, release to re-mask. Use it for secrets like API keys or tokens so they aren't shoulder-surfed.
"apiKey": {
"type": "password",
"label": "API key",
"placeholder": "sk-…"
}
textarea
Multi-line text. Same options as text-field.
"notes": {
"type": "textarea",
"label": "Notes",
"placeholder": "Long-form text…"
}
number
Numeric input. Accepts integers or floats.
"precision": {
"type": "number",
"label": "Precision",
"default": 2
}
checkbox
Boolean toggle.
"verbose": {
"type": "checkbox",
"label": "Verbose output",
"default": false
}
date
Date picker. Stored as YYYY-MM-DD.
"due": {
"type": "date",
"label": "Due date",
"clearable": true
}
file
File upload (input) or downloadable file reference (output). On input, the user picks a file from disk and your code receives its filename; on output you return a file for the user to download. See Files for how to read and write the bytes from inside process.
| Option | Description |
|---|---|
accept | Comma-separated MIME types or extensions, e.g. "image/*,.csv". |
multiple | Accept multiple files. |
maxSize | Max bytes per file. |
maxFiles | Max number of files when multiple is set. Picking past the limit appends only what fits and shows an inline "N files maximum" error — it doesn't reject the whole selection. |
"upload": {
"type": "file",
"label": "Upload CSV",
"accept": ".csv",
"maxSize": 5242880
}
color
Single color picker. Stored as a hex string.
| Option | Description |
|---|---|
showTextField | Show a hex input next to the swatch. |
showSwatches | Show preset color swatches. |
"brand": {
"type": "color",
"label": "Brand color",
"default": "#FF3C00",
"showTextField": true
}
color-palette
A list of hex colors that the user can add to or remove from. Stored as an array of strings.
"palette": {
"type": "color-palette",
"label": "Palette",
"default": ["#FF3C00", "#1A0A05"]
}
list
Array of homogeneous items. Use itemType to declare the type of each item — any field type from this page is allowed.
| Option | Description |
|---|---|
itemType | Field type used for each item. Defaults to text-field. |
addValueButtonText | Custom label for the "add item" button. |
"keywords": {
"type": "list",
"label": "Keywords",
"itemType": "text-field",
"default": []
}
Outputs
Output fields use the same type values as inputs. They're rendered as read-only by default. Add copiable: true to make them easy to copy:
"output": {
"result": {
"type": "text-field",
"label": "Result",
"copiable": true
}
}
Settings
Settings declared under the top-level settings block use the exact same field types and options as inputs. They appear in a separate panel and persist across runs.