●Configuration

Fields reference

Every built-in field, every property, and how hidden metadata works. Consistent across all SDKs — the names and shapes below are the same on web, mobile, iframe, and HTML fallback.

01System fields

System fields

These have built-in types and max-length validation. Use them by name to get the right label and input type automatically.

Name	Type	Default label	Max length	Defaults required?
subject	text	Subject	200	Yes
description	textarea	Description	5000	Yes
email	email	Email	254	No
name	text	Name	100	No
url	url	URL	2048	No
phone	tel	Phone	20	No

02Field properties

Field properties

Every field (system or custom) is configured with this shape:

Property	Type	Description
visible	boolean	Show the field in the form UI. Hidden fields still go through to the issue.
required	boolean	Only applies when visible: true. Enforced client-side and server-side.
value	string \| any	Default for visible fields; the actual value for hidden fields.
label	string	Override the field label in the UI.
placeholder	string	Placeholder text for visible inputs.
type	'text' \| 'email' \| 'textarea' \| 'url' \| 'tel' \| 'number' \| 'select'	Override the input type. Defaults to the type of the matching system field.
options	string[]	Options list for type: "select" fields.
maxLength	number	Max character count for text/textarea.
minLength	number	Min character count for text/textarea.
pattern	string (regex)	Client-side validation pattern.
validationMessage	string	Message shown when validation fails.

fields.js

fields: {
  subject: {
    visible: true,
    required: true,
    label: "What's up?",
    placeholder: "e.g. Can't submit my order",
    value: "Bug Report"
  },
  userId: {
    visible: false,
    value: currentUser.id
  }
}

03Hidden metadata

Hidden metadata

Set visible: false with a value to attach context to every submission. The metadata shows up in the body of the created issue, so the engineer picking it up has what they need.

hidden-metadata.js

fields: {
  subject:     { visible: true, required: true },
  description: { visible: true, required: true },
  email:       { visible: false, value: currentUser.email },
  userId:      { visible: false, value: currentUser.id },
  plan:        { visible: false, value: currentUser.plan },
  appVersion:  { visible: false, value: APP_VERSION },
  pageUrl:     { visible: false, value: window.location.href },
  sessionId:   { visible: false, value: analytics.sessionId() }
}

04Select fields

Select fields

Render a dropdown by setting type: 'select' and providing options:

select-field.js

fields: {
  priority: {
    visible: true,
    required: true,
    type: 'select',
    label: 'Priority',
    options: ['Low', 'Normal', 'High', 'Blocker']
  }
}

05Provider-specific fields

Provider-specific fields

These are only read when your project targets the matching provider. A github_labels field is ignored on a Linear project, and vice versa.

GitHub

github_labels: Comma-separated GitHub label names (case-sensitive).
github_assignees: Comma-separated GitHub usernames. Must have write access to the repo.
github_milestone: GitHub milestone number.

github_labels:    { visible: false, value: "bug,customer" },
github_assignees: { visible: false, value: "johndoe" }

Linear

linear_labels: Comma-separated Linear label IDs(not names). Appended to the project's default labels, not replacing them.

linear_labels: {
  visible: false,
  value: "a1b2c3d4-...,e5f6g7h8-..."
}

More on Linear defaults in the Linear features guide.

06Validation

Validation

Required visible fields must be non-empty at submit time.
Text and textarea fields enforce maxLength / minLength on both client and server.
Email fields are validated against a standard email regex.
Custom pattern regexes are client-side only — the server accepts the value as-is.
Intercept validation failures with the onValidationError callback.