14.3.0 [Current] 13.3.1 [Past] 12.7.4 [Past]

FormGroup

import FormGroup from '@concur/nui-widgets/lib/Forms/FormGroup';

Form groups encapsulate components related to a single form input. At a minimum, it should contain ControLabel and FormControl child components. Many FormGroup properties will be transformed or passed along to its children so these values will not need to be manually re-specified.

NOTE: Checkbox controls are not allowed inside FormGroup as they are self-labeling.

NOTE: Form groups have no explict width so they rely on the size of their child components. Starting in Version 12, any child component with a .form-control class (FormControl, Dropdown, TextArea, Password) will have its width set to 100%. Because of that, form groups should be laid out on the page in sized containers (e.g. columns) to avoid them spanning the entire width of the window.

Examples

Sizes

Three sizes are supported: 'lg' (the default), 'md' and 'sm'. Use the size property to set the size.

Note the use of the FormGroup.HelpBlock component to provide additional explanatory text in the following example.

<FormGroup
    controlId={shortid.generate()}>
    <ControlLabel>Large</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

<FormGroup
    controlId={shortid.generate()}
    size='md'>
    <ControlLabel>Medium</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

<FormGroup
    controlId={shortid.generate()}
    size='sm'>
    <ControlLabel>Small</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

ReadOnly

Use the readOnly property to mark form controls as readonly. Input controls will have the readonly attribute set so that they can receive focus, to support keyboard-only navigation and other assistive technologies.

Notes:

• Do not set both readOnly and required properties. This will throw a PropType validation error because readonly form controls are barred from any kind of constraint validation.
• Do not set both readOnly and validationMessage properties. This will throw a PropType validation error because readonly form controls are barred from any kind of constraint validation.
• Do not set readOnly on a form group when the underlying form control is a Dropdown. This will throw a PropType validation error because the <select> element cannot have readonly set.

<FormGroup
    controlId={shortid.generate()}
    readOnly>
    <ControlLabel>Label</ControlLabel>
    <FormControl value={'Readonly Value'} />
    <FormGroup.HelpBlock>You cannot edit this value</FormGroup.HelpBlock>
</FormGroup>

Required

Use the required property to mark form controls as required. Labels will display a visual indication while input controls will have a required attribute added to help with assistive technologies.

<FormGroup
    controlId={shortid.generate()}
    required>
    <ControlLabel>Label</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

Validation States

Validation state properties apply only to FormGroup components (not individual ControlLabel or FormControl components). The validation tooltip will be triggered when hovering over the icon next to the ControlLabel and also when the FormControl receives focus. Use the validationMessage property to set a validation state.

<FormGroup
    controlId={shortid.generate()}
    validationMessage={{ state: 'warning', text: 'Validation warning message' }}>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

<FormGroup
    controlId={shortid.generate()}
    validationMessage={{ state: 'error', text: 'Validation error message' }}>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

Validation Message Type

Use the validationMessageType property to change how the validation message will display if one is present. The validation message will display 'iconAligned' by default like the above example in validation states. By selecting 'inputAligned', the validation message will display as an overlay underneath the input.

<FormGroup
    controlId={shortid.generate()}
    validationMessage={{ state: 'warning', text: 'Validation warning message' }}
    validationMessageType='inputAligned'>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

<FormGroup
    controlId={shortid.generate()}
    validationMessage={{ state: 'error', text: 'Validation error message' }}
    validationMessageType='inputAligned'>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

Usage

Properties