Skip to content

EnFormGroup ​

Preview ​

Props ​

NameDescriptionDefaultControl
field

A single field object to dynamically create the input inside of the form group. Key-value pairs can be any valid props for input components.

Record<string, any>
unknown
inputGroupProps

Layout for this group's label and field, as an InputGroupProps object. Set it per group to give one field a different split from the rest of the form, or pass through the form-wide values EnForm offers on its fields slot when a group should match the ones it generates.

{Object}
unknown
showRequired

Displays asterisk (*) next to the label to indicate a required field.

boolean
true
horizontal

Sets the layout of the label to the left of the form field. Note: must be inside a form-horizontal classed form or div.

boolean
false
label

Label text to display.

string
""
hideLabel

Does not render a label and adds aria-label to the input. The label icons (tooltip, critical warning, lock) need a visible label to sit beside, so none render in this mode; the control itself still shows its critical glow, in-input lock and disabled state.

boolean
false
displayOnly

Passes down the displayOnly prop to the input.

boolean
false
emptyValue

Passes down the emptyValue prop to the input, unless the input sets its own: what a display-only field shows in place of an empty value. true is an em dash; a string is shown as given.

string | boolean
false
tooltip

Text for an info tooltip rendered after the label, ahead of the label-inner slot. Uses en-components' EnTooltip when the consuming app has registered it globally, and falls back to a titled info icon otherwise.

string
""
tooltipProps

Extra props for the EnTooltip or EnPopover behind tooltip, passed straight through, such as maxWidth, placement or, for a popover, title. Max width defaults to 250px for a tooltip and 300px for a popover.

{Object}
{}complex object
popover

Shows tooltip as a click-to-open EnPopover with a title bar instead of a hover EnTooltip. Needs the consuming app to have registered EnPopover globally.

boolean
false
critical

Marks the field critical: passed down to the input as its critical prop, and adds a warning icon after the label while the field is empty. Setting critical on the input itself has the same effect. Critical is not required: it is for a field that can be left empty now but must be filled before something later can happen, such as activating or completing a record.

boolean
false
locked

Locks the field: passed down to the input as its locked prop, which disables it and shows a lock icon. Text-like inputs show the lock inside the control; option groups, file inputs and the like show it after the label here. Setting locked on the input has the same effect.

boolean
false

Slots ​

default

Accepts any EnInput to pair with a label element.

after

Renders alongside the input, after it, inside the same form group. For a control that adjusts the field's value rather than holding it — an `EnStepper`, say — which belongs beside the input but not inside its input group.

label-inner

Renders inside the label element, after the text provided by the label prop and required asterisk. Can be used to customize the label or add a tooltip.

Events ​

No events defined.

Methods ​

No methods defined.

Types ​

InputGroupProps - Object

Layout values for a form group's label and field. Set per group, so different fields in the same form can take different splits — a wide label on one row and the default on the next. EnForm also builds one from its own horizontal, showRequired, labelClass and inputClass props, hands it to the groups it generates from fields, and exposes it on the fields slot for groups that should match those.

NameTypeDescription
horizontalboolean

Lays the label to the left of the field rather than above it. Requires an ancestor with the form-horizontal class.

showRequiredboolean

Shows an asterisk (*) next to the label of a required field.

labelClassstring

Column class for the label in the horizontal layout, e.g. 'col-md-3'. Only takes effect alongside inputClass — the two are the columns of one row.

inputClassstring

Column class for the field in the horizontal layout, e.g. 'col-md-9'. Only takes effect alongside labelClass.

Guidelines ​

Layout is set per group, not per form ​

inputGroupProps carries the four layout values above as one object, and it is set on the group. That's what lets one row take a wide label while the next takes the default — the splits don't have to be uniform across a form.

labelClass and inputClass are the two columns of one row, so they only take effect together; setting one alone does nothing. Both need an ancestor carrying form-horizontal, and horizontal has to be on as well.

Where the object usually comes from ​

EnForm builds an InputGroupProps from its own horizontal, showRequired, labelClass and inputClass props, hands it to every group it generates from fields, and exposes it on the fields slot. So a group you write by hand inside that slot can match the generated ones by passing it straight through, rather than restating the four values and drifting from them:

Any group can override its own instead — pass a different object and that row alone changes:

For the newer CSS-only alternative — a fixed label column with the control sized to its content, which needs no per-group object — see inline form groups.

Tooltip, critical and locked fields ​

Three things can follow a label's text, and the group renders all of them the same way so every label reads alike: the required asterisk stays alone on the left, and the icons trail the text in a form-label-indicators row.

  • tooltip renders an EnTooltip after the label text, with a 250px max width so a sentence or two fits. Add popover to show it instead as a click-to-open EnPopover with a title bar (300px max width), for an explanation long enough that the reader should open it on purpose rather than on hover. tooltipProps passes anything else through: placement, maxWidth, or a popover's title. Prefer this over dropping an EnTooltip into label-inner yourself. The tooltip still shows when the field is displayOnly, because what a value means holds whether or not it can be edited. Keep to one trigger per field; the forms styleguide says when help text is the better home. The group has no help text prop yet (proposed in front-end/beacon#40), so a help-block — permanent guidance or a state-specific notice — is rendered directly after the group, not in the after slot, which sits on the field's line.
  • critical is for a field that can be left empty now but must be filled before something later can happen, such as activating a plan or completing a record. It is not required: a required field blocks saving, a critical one does not. While the field is empty the control takes a yellow highlight and the label gains a warning icon; both clear once it holds a value and return if it is cleared again. A validation error still wins.
  • locked disables the control and marks it with a lock. Text-like controls draw the lock inside the input, where a select keeps its arrow; option groups, booleans and file inputs have no box, so the lock joins the label here instead. Give the input a lockedMessage ("Locked while payroll is open") and it shows as a tooltip on the control and on the lock icon, which becomes focusable so keyboard users can reach the text that the disabled control cannot offer.

critical and locked can be set on the group or on the input; either side flags the field, and the group reads the merged result back for its icons. lockedMessage goes on the input. Both describe editing, so a displayOnly field shows neither. A group with hideLabel renders no icons, since there is no label for them to sit beside, but the control still shows its highlight, in-input lock and disabled state.

Type into the first field and the critical highlight clears; empty it again and it returns.

Empty values in display-only fields ​

A displayOnly field with no value renders nothing, which on a read-only summary can look like a missing row rather than a blank answer. emptyValue puts a placeholder there instead: true shows an em dash, and a string shows that text ("Not provided"). It is drawn in gray-700 so it reads as "nothing here" rather than as a value, and it only applies while the field is display only.

Set it on the input, on the group, or once on EnForm for every field it displays. A group or form passes it down unless the input sets its own.

Examples ​

A control beside the field ​

The after slot renders alongside the input, inside the same form group, for a control that adjusts the field's value rather than holding it. The group wraps the pair in a btn-container btn-container-nowrap row, so the extra control lands on the field's line instead of underneath it.

This is how EnInputStepper attaches to a field. It is not for a second input — two inputs in one group have no label association between them.

A tooltip in the label ​

label-inner renders inside the label element, after the text, the required asterisk and the label icons — so it is read as part of the label rather than as loose content in the group. For a plain info tooltip use the tooltip prop instead; the slot is for anything else the label should carry, such as a link or a chip.

  • EnForm — Builds groups from fields and supplies the form-wide inputGroupProps.
  • EnLabelIndicators — The icon row the group renders, for a label you build by hand.
  • Forms styleguide — The underlying classes, including the inline layout.