.do-dont{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin:16px 0}
@media(max-width:640px){.do-dont{grid-template-columns:1fr}}
.do{border-left:4px solid #1A7F5A;padding:12px 16px;background:#F0FDF4;border-radius:0 4px 4px 0}
.dont{border-left:4px solid #B91C1C;padding:12px 16px;background:#FFF5F5;border-radius:0 4px 4px 0}
.do-dont-label{font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;margin-bottom:8px}
.do-label{color:#1A7F5A}
.dont-label{color:#B91C1C}
.do-dont-content p{margin:0;font-size:13px;line-height:1.6}
.spec-table{width:100%;border-collapse:collapse;font-size:13px;margin:12px 0}
.spec-table th{text-align:left;padding:8px 12px;background:#F3F4F6;font-weight:700;font-size:11px;text-transform:uppercase;letter-spacing:.04em;color:#6B7280;border-bottom:2px solid #E5E7EB}
.spec-table td{padding:8px 12px;border-bottom:1px solid #F3F4F6;vertical-align:top;line-height:1.5}
.spec-table code{background:#F3F4F6;padding:1px 5px;border-radius:3px;font-size:12px}
.related-pages{margin-top:32px;padding-top:20px;border-top:1px solid #E5E7EB}
.related-pages h3{font-size:13px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:#6B7280;margin-bottom:10px}

# Form controls

Form controls are the interactive input elements used in Petrel dialogs and property panels. Consistent behaviour and labelling are essential for usability and accessibility.
## When to use

Use form controls in dialogs, property sheets, and settings panels where users enter, select, or modify data. Choose the control type that best matches the data type and the user's mental model of valid input.

## When not to use

Do not use text input fields where a constrained selection is more appropriate (use a dropdown or radio group). Do not use checkboxes for mutually exclusive options (use radio buttons).

## Control selection guide

Data type
Recommended control
Notes
Free text (short)
TextBox (single line)
Validate inline; show error below field
Free text (long)
TextBox (multi-line)
Show character count if there is a limit
Number (known range)
NumericUpDown / Spinner
Show units adjacent to field; see Numeric precision
Selection from list (few items)
RadioButton group
Use for 2–5 mutually exclusive options
Selection from list (many items)
ComboBox
Include search for lists over 10 items
Boolean yes/no
CheckBox
Label must describe the checked state
Date
DatePicker
Always allow manual text entry in addition to picker
## Anatomy of a form field

Each form field consists of:

1. **Label** — Descriptive text above or to the left of the control. Required for all inputs.
2. **Input control** — The WPF control itself.
3. **Helper text** (optional) — Format guidance or constraints below the control.
4. **Error message** — Appears below the control when validation fails. Includes an error icon.


## Do and Don't

DO
Place form labels above input fields (not to the left) when the dialog contains many fields in a vertical list. Labels above fields improve scannability and work better at narrow dialog widths.
DON'T
Don't use placeholder text as a substitute for a visible label. Placeholder text disappears when the user starts typing, removing the label at exactly the moment they might need to refer back to it.
## Accessibility requirements

- Every input control must have a visible label that remains visible when the input has a value.
- Labels must be programmatically associated using `AutomationProperties.LabeledBy`.
- Required fields must be marked both visually (asterisk or "Required" text) and in the accessibility tree (`AutomationProperties.IsRequiredForForm = true`).
- Validation errors must be announced to screen readers via `AutomationPeer` live region notifications.


### Related pages

Dialogs
— Form controls in dialogs
Numeric precision
— Number input formatting
Labels and accessible names