Form field

Anatomy

The grid invariant

Fields live in rows of two. A row with a single leftover field keeps the width of ONE column: it does not stretch to fill the row. Full width is reserved for a primary field that sits alone in its own block (Name) and is opt-in via FieldRow's full. This is what keeps hundreds of provider forms reading as one form. Three fields are always two on top and one at half width below, never a layout that reflows differently per provider.

Controls

Two shorthands cover the common case: an Input by default, a dropdown when you pass options. Search is not a second component you have to choose — it is a property of that dropdown, and the length of the list earns it. Under eight options the list opens fully visible and reading it beats typing, so a search box would be furniture; past eight it starts scrolling, and the countries and currencies a provider form is full of stop being findable by eye. The kit ships a Select and a Combobox, which is an inheritance rather than a decision a form author should make field by field, so Field makes it for them — and `searchable` overrides it where the count lies. Everything the shorthands do not cover goes in as children and still gets the field's id, so the label keeps pointing at it.

Helper and error

description prints muted helper text under the control. error replaces it, turns it destructive and tints the control border with the same triplet the Input doc documents, so a field in error looks identical whether it was built here or by hand.

Blocks

A block is a titled group of rows, 24px apart. Blocks are separated by a Separator that the screen owns: the block never draws its own rule, so the screen decides where the divisions go.

The box

FieldGroup is the box a group of fields sits in. Acquirer BIN, metadata, Requestor ID and the multi-MID add box are not four boxes that look alike — they are this one box, and the next box of the same kind is this one too rather than a fifth built by hand. It is deliberately NOT a card: a card is a top-level surface on the page canvas, and this is the step below it, the third rung of the ladder — canvas 250/10, panel 255/23, group 255/38. Its fill is dark-only on purpose. In light the group is carried by its border, exactly as it is today, so adopting it changes nothing in the default theme — which is why any grey here reads as too much. In dark a border alone was not enough: the group had the same fill as the panel around it and dissolved into it. Ported from dashboard-web's FieldGroup molecule, so the kit and production say the same thing rather than each inventing a box.

Progressive disclosure

A checkbox that reveals the fieldset it governs. The common path stays short and the extra fields only exist once the merchant opts into them. Common in Connection and Routing setup.

Repeatable groups

Anything the merchant can add more of: acquirer BINs, requestor IDs, metadata. One container card, item cards inside, an Add control, and a delete column that only appears once there is more than one item, because you cannot remove the last one.

The exception: the inline bar

One row in this vocabulary is not two columns. FieldBar puts N short fields on a single line, because it is collecting one short record the merchant is about to add to a list, over and over, and not the settings of one thing. It is a 12-column grid, which is what span always meant: the columns line up down the box and a line costs its control height and nothing else. Labels print ONCE, as a row of the box rather than as children of their controls — every line used to be its own bordered card with its own labels, which cost about 120px a line and made four merchant IDs taller than the rest of the step. The box around it belongs to the screen: only the header row and the lines are the pattern. Ported from multi-mid's Merchant IDs, where the shape was designed and picked apart — Upload file sits at title level because at 150 merchant IDs the file is the real path and typing is the exception, so it is not a peer of the typing controls.

Stacked lines

A merchant adding three or four records should not have to add, retype, add. Extra lines stack on the same 12-column grid under the one header row, and one button commits all of them. The removal control appears from the second line on — you cannot remove the only line there is, and a lone X on an empty box is noise. The two buttons stop being peers by placement rather than wording: Add more belongs to the BOX and lives inside it, under the lines it makes, while the primary belongs to the STEP and sits under the box, in the slot the single-line version puts its Add.

The rows answer to width, not to the window

Every FieldRow and every FieldBar is its own container, so the layout answers to the width the form actually got. There is no sheet prop to pass and no second component to maintain. The numbers are honest about what that buys here: the kit's Sheet is 768px wide, 719px of usable body, which is as wide as a wizard step (766px) — so a form in a Sheet keeps its two columns and the bar keeps its line. The fold is for containers that are genuinely narrow: a row drops to one column under 576px, and the bar folds to two lines of two under 672px, inside the same card, never one field per line and never spilling out of the container.

Import

Import the pieces you compose. Field covers the two control shorthands, and anything else goes in as children.

Props

Everything else is forwarded to the underlying elements via ...props.

Related

Cross-links to the atoms this molecule composes and sibling patterns.