Fields and layout - Serval Documentation

Describe the fields you want to Catalyst. This page is the reference for what’s available.

Field types

Field	Asks for	Submitted value
`text`	Free text, single- or multi-line	The string
`number`	A numeric value	The number
`boolean`	A yes/no toggle	`true` or `false`
`select`	One option from a list	The option’s value
`multiSelect`	Several options from a list	A list of values
`cards`	One option from a visual grid	The option’s value
`date`	A calendar date	`"YYYY-MM-DD"`
`time`	A time of day	24-hour `"HH:MM"`
`datetime`	A specific instant	RFC 3339 in UTC
`duration`	A length of time	Whole seconds
`attachment`	A file upload	The attachment ID
`entity`	One record from a database table	The record ID
`entityList`	Several database records	A list of record IDs
`user`	One person in your organization	The user ID
`userList`	Several people	A list of user IDs

Every field takes a label, optional help text under the label, and a message that replaces the default error copy.

Validation

Serval enforces constraints, not the browser. A violation shows an error on the field and blocks submit on every surface.

Field type	Constraints
`text`	`format: "email" \| "url"`, `pattern`, `minLength`, `maxLength`
`number`	`min`, `max` (inclusive)
`date`	`min`, `max` as absolute dates: `"2026-03-01"`
`time`	`min`, `max` as 24-hour times: `"17:30"`
`datetime`	`min`, `max` as RFC 3339. A bound with no time zone reads as UTC
`duration`	`min`, `max` in seconds. Write them as arithmetic: `30 * 86400`
`multiSelect`, `entityList`, `userList`	`minItems`, `maxItems`
`attachment`	`acceptedFileTypes`: MIME types, wildcards (`"image/*"`), or extensions (`".csv"`)

Constraints never fire on an empty answer. required owns emptiness. An optional field with a maxLength is checked only once somebody types in it.

Date bounds are absolute. There’s no “no earlier than today,” because the form renders without a trustworthy clock. A rule that moves with the calendar belongs in the submit workflow.

Choice fields

select and multiSelect options can carry a description shown as secondary text. Slack truncates descriptions after 75 characters. The submitted value is unchanged. cards renders options as a grid of tiles with optional images: the right choice when somebody is picking a thing, like a laptop model or an office location.

const [model, Model] = field.cards("model", [
  {
    value: "mba",
    label: "MacBook Air (M-series)",
    description: "Lightweight macOS laptop for everyday work and travel.",
    imageUrl: "https://example.com/images/macbook-air.png",
  },
], { label: "Choose your laptop", columns: 2 });

Card images must be https URLs and load directly in the filler’s browser. Serval doesn’t host or proxy them, so use an image that’s publicly reachable and expected to stay that way. columns accepts 2, 3, or 4 and defaults to 3.

Database and user fields

entity and entityList turn a database table into a searchable picker, so requesters choose real records instead of typing names that match nothing. You pick which field shows as the label, which is submitted as the value, and which appears as secondary text. Filters can key off another field’s current answer, so choosing an application narrows the entitlements below it. user and userList pick from your organization:

Filter	Effect
`teamId`	Only members of that team
`groupId`	Only members of that group
`roles`	Only users holding one of the listed roles
`includeDeactivated`	Include deactivated users. Off by default

teamId and groupId are mutually exclusive. Setting both fails at render time rather than dropping a filter.

Layout

Element	Purpose
`Section`	Groups questions under a heading with an optional icon. `columns={2}` lays them out side by side
`Notice`	A call-out. `tone` is `info`, `success`, `warning`, or `danger`
`Divider`	A rule between groups

The <Form> root carries identity and look: header (title, subtitle, icon), accent (brand, blue, green, yellow, orange, red), density (comfortable, compact), and surface (plain, tinted, gradient).

<Form header={{ title: "Laptop Request", icon: "laptop" }} accent="brand">
  <Section title="Device" icon="laptop">
    <Model required />
  </Section>
  <Divider />
  <Section title="Details" icon="clipboard" columns={2}>
    <ForWhom />
    <NeededBy />
  </Section>
</Form>

Colors and icons come from fixed lists, so forms match the rest of the product and render correctly everywhere, including Slack. An unrecognized name fails at publish instead of rendering nothing.

Logic and workflows

Conditional fields and live data from your systems.

Share and fill

Where forms appear and how each surface renders them.

​Field types

​Validation

​Choice fields

​Database and user fields

​Layout

Logic and workflows

Share and fill

Field types

Validation

Choice fields

Database and user fields

Layout