Form page

A form page collects the fields for one record and saves it. It opens over the page it was started from, and that page stays behind it.

When to use one

Use a form page when a customer is creating or changing one record and the fields do not fit in the row or the menu they started from.

Do not use one for a setting that applies the moment it is changed. That is a toggle on the page itself. Do not use one to show a record that already exists and is not being edited. That is a detail page.

Forms owns the field-level rules: which control to use, how to mark a field required, where help text goes, how to group and size the fields. This page is the surface those rules sit in.

Anatomy

Wireframe of a form page. The application header and the page behind it are drawn faint, because the form opens on top of them. Above the form, a title reads New trigger on the left and a close cross sits at the far right. The form itself is three columns. The left column is a rail headed Pick a metric, with grouped entries under Tracing, Host metrics and Other, and Error rate selected. The middle column opens with the name of the chosen variant and a two-line description, then a divider, then fields in one column: a namespace select, a percentage threshold with the unit inside the input, a warm-up in minutes with a help icon beside its label, a checkbox, a divider, a description box, a divider, and a footer holding a filled Save trigger button with Cancel beside it. The right column is headed Error rate chart preview and holds a chart with a flat line, above a row of range buttons from 1H to 30D.

The page behind stays where it is and is not usable while the form is open. The regions below are the form's own.

RegionWhat it holdsRule
1HeaderThe record being made, and the way outName the record, not the act. The close control belongs here rather than in the body, because closing without saving must not scroll out of reach
2Type railThe variants that change which fields appearPresent only when a variant changes the fields themselves. Moving between entries swaps the form rather than editing a value in it, so the rail sits outside the fields it switches
3Form headerThe chosen variant, named, and one line saying what the saved record will doOne line. Anything longer is field help, and belongs beside the field it explains
4Form bodyThe fields, in one column, grouped by dividerThe page type fixes the column and nothing else. Control choice, required markers, help, grouping and widths are on /patterns/forms.md
5PreviewThe result, and the controls the result needsPresent only when the result is visual. It is the one thing the side panel may hold. With nothing to show it carries an empty state rather than an empty frame
6FooterThe save, and the way out beside itOne primary, left-aligned, with Cancel next to it. It sits at the foot of the form column rather than the overlay, under the fields it submits

Regions 2 and 5 are conditional and often both absent. A form with no variants and no visual result is one column.

Wireframe of the same form with its two conditional regions gone. Where the type rail and the preview would sit, two dashed outlines are labeled no type rail and no preview. The form column stands alone in the middle, holding a name field and a query field each marked Required at the right of the label, a threshold select, a group of severity checkboxes with a line beneath reading that leaving all unchecked filters on all severities, a divider, and a footer whose Save trigger button is dimmed because nothing has been filled in yet.

States

StateWhat it saysWhat happens next
Nothing filled inThe form has just openedMark the required fields and leave the primary unusable. The marker is the explanation, so no sentence is needed to say the form is incomplete
A value is wrongOne field cannot be saved as enteredLeave every value in place and keep the form open. A form that clears the field removes the evidence of the mistake. Where the message itself goes is a field-level rule, and /patterns/forms.md is where it belongs
SavingThe record is being writtenKeep every field visible and the primary unusable. The form has nowhere to put what was typed if it blanks and the save then fails
The save failedThe record was not writtenSay what failed and leave every value in place. Retyping a long form is the cost of clearing it
The preview has nothing to showThe fields so far do not describe a resultSay which field would produce one, following the empty state pattern. An empty frame reads as a broken preview

What the form arrives with

A form is opened from somewhere, and that place is context the form already has. A form opened from one dashboard, one application or one namespace does not ask which one.

Comes in from the page behindIs asked for in the form
The record the form will belong to, such as the dashboard or the applicationEverything about the new record itself
The scope already set, such as the namespaceA scope the new record needs and the page behind cannot supply

Closing returns to the page the form opened over, unchanged. Saving returns to the same place with the new record in it. Neither lands on a list, because the form was not opened from one.