Forms

import { Forms } from '@concur/nui-widgets';

Forms are used to collect data from the user. A number of different components can be used to build forms, such as ControLabel, FormControl, Checkbox, Fieldset, FormGroup, TextArea and Password. Note that FormControl components can emit <input>, <select> or any other type of HTML form element, depending on the value of its componentClass property.

Examples

Sizes

All form components support three sizes: 'lg' (the default), 'md' and 'sm'. Use the size property to set the size.

The following demonstrates the use of the size property and the ControLabel component, as well as various types of FormControl components.

Show Code

<!-- Text input elements -->
<ControlLabel>Large Label</ControlLabel>
<FormControl />

<ControlLabel size='md'>Medium Label</ControlLabel>
<FormControl size='md' />

<ControlLabel size='sm'>Small Label</ControlLabel>
<FormControl size='sm' />

<!-- Password input elements -->
<ControlLabel>Large Password Label</ControlLabel>
<Password />

<ControlLabel size='md'>Medium Password Label</ControlLabel>
<Password size='md' />

<ControlLabel size='sm'>Small Password Label</ControlLabel>
<Password size='sm' />

<!-- Textarea elements -->
<ControlLabel>Large Textarea Label</ControlLabel>
<TextArea />

<ControlLabel size='md'>Medium Textarea Label</ControlLabel>
<TextArea size='md' />

<ControlLabel size='sm'>Small Textarea Label</ControlLabel>
<TextArea size='sm' />

<!-- Select elements -->
<ControlLabel>Large Select Label</ControlLabel>
<FormControl componentClass='select'>
    <option value='select'>Select Item</option>
    <option value='item1'>Item 1</option>
    <option value='item2'>Item 2</option>
</FormControl>

<ControlLabel size='md'>Medium Select Label</ControlLabel>
<FormControl componentClass='select' size='md'>
    <option value='select'>Select Item</option>
    <option value='item1'>Item 1</option>
    <option value='item2'>Item 2</option>
</FormControl>

<ControlLabel size='sm'>Small Select Label</ControlLabel>
<FormControl componentClass='select' size='sm'>
    <option value='select'>Select Item</option>
    <option value='item1'>Item 1</option>
    <option value='item2'>Item 2</option>
</FormControl>

Checkbox

Checkbox is a specialized form control that emits an <input> with a type of checkbox.

States

Different states of a checkbox can be set using the checked, indeterminate and disabled properties.

Show Code

<Checkbox
    label='Standard Example' />
<Checkbox
    checked
    disabled
    label='Disabled Example' />
<Checkbox
    checked
    indeterminate
    label='Indeterminate Example' />

Inline

Inline checkboxes will be shown on the same horizontal row rather than stacked. Use the inline property for this option.

Show Code

<Checkbox
    inline
    label='Standard Example' />
<Checkbox
    checked
    disabled
    inline
    label='Disabled Example' />
<Checkbox
    checked
    indeterminate
    inline
    label='Indeterminate Example' />

Fieldset

There is a breaking change to this component in the next version of NUI Widgets.

Fieldsets are used to give semantic meaning to a group of elements inside a form (e.g. Billing or Shipping Address). Grouping fields together into a fieldset also provides styling and accessibility benefits. Use the classicFieldset and muted properties to alter the styling of a fieldset.

Show Code

<Fieldset
    legend='Legend'>
    <FormGroup>
        <ControlLabel>Fieldset Test Input</ControlLabel>
        <FormControl />
    </FormGroup>
</Fieldset>

<Fieldset
    classicFieldset
    legend='Legend'>
    <FormGroup>
        <ControlLabel>Fieldset Test Input</ControlLabel>
        <FormControl />
    </FormGroup>
</Fieldset>

<Fieldset
    legend='Legend'
    muted>
    <FormGroup>
        <ControlLabel>Fieldset Test Input</ControlLabel>
        <FormControl />
    </FormGroup>
</Fieldset>

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 the use of the FormGroup.HelpBlock component to provide additional explanatory text in the following example.

Show Code

<FormGroup
    controlId='formgroup'>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

Required Controls

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.

Show Code

<ControlLabel required>Required Label</ControlLabel>

<FormGroup
    controlId='formgroup'
    required>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
    <FormGroup.HelpBlock>Help block text</FormGroup.HelpBlock>
</FormGroup>

<Checkbox
    checked={checkState}
    label='Option 1'
    onChange={(value) => {
        this.setState({
            checkState: value
        });
    }}
    required />

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.

Show Code

const warningMsg = {
    state: 'warning',
    text: 'Validation warning message'
};
const errorMsg = {
    state: 'error',
    text: 'Validation error message'
};

<FormGroup
    controlId='formgroup1'
    validationMessage={warningMsg}>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

<FormGroup
    controlId='formgroup2'
    validationMessage={errorMsg}>
    <ControlLabel>FormGroup Label</ControlLabel>
    <FormControl />
</FormGroup>

<Checkbox
    label='Option #1'
    validationMessage={warningMsg} />
<Checkbox
    label='Option #2'
    validationMessage={errorMsg} />

Usage

ControlLabel

Properties

Property	Type	Default	Description
`bsClass`	String	`'control-label'`	Base CSS class and prefix for the component. One should not generally change `bsClass` except to add new, non-Bootstrap CSS styles to a component.
`className`	String		Any custom classes to add to the `<label>` element.
`htmlFor`	String		Sets the `for` attribute on the `<label>` element. If used within a `FormGroup`, the `controlId` property will be used. This property overrides that.
`required`	Boolean	`false`	Appends the required field indicator (red asterisk) to the end of the label text.
`size`	String	`'lg'`	Size of the `<label>` element. Options are `'lg'`, `'md'`, `'sm'`.
`validationMessageState`	String		If used in conjunction with field validation, this provides the icon next to the label. Options are `'error'`, `'warning'`.

FormControl

Properties

Property	Type	Default	Description
`bsClass`	String	`'form-control'`	Base CSS class and prefix for the component. One should not generally change `bsClass` except to add new, non-Bootstrap CSS styles to a component.
`className`	String		Any custom classes to add to the `<input>`, `<textarea>` or `<select>` `componentClass` element.
`componentClass`	Element	`'input'`	Often `'input'`, `'textarea'` or `'select'`, but any valid HTML form element can be supplied.
`id`	String		Sets the `id` attribute on the `<input>`, `<textarea>` or `<select>` `componentClass` element. If used within a `FormGroup`, the `controlId` property will be used. This property overrides that.
`inputRef`	Function		Attaches a ref to the `<input>` element.
`required`	Boolean	`false`	Adds the `required` attribute to the `<input>` element. NOTE: This does not perform any validation, but rather just marks the field as required.
`size`	String	`'lg'`	Size of the `<input>` element. Options are `'lg'`, `'md'`, `'sm'`.
`type`	String	`'text'`	Type of form control to emit. Options are `'text'`, `'textarea'`, `'select'`.
`validationMessageState`	String		If used in conjunction with field validation, this provides the icon next to the label. Options are `'error'`, `'warning'`.

Callbacks

Property	Parameters	Description
`onBlur`	`event`	Callback function for onBlur events.
`onFocus`	`event`	Callback function for onFocus events.

Checkbox

Properties

Property	Type	Default	Description
`label`	String	Required	Text label for checkbox input.
`checked`	Boolean	`false`	When `true`, the checkbox renders as “checked”.
`className`	String		Any custom classes to add to the `<label>` element.
`disabled`	Boolean	`false`	When `true`, the checkbox gets the `disabled` attribute.
`hiddenLabel`	Boolean	`false`	When `true`, the label will not be shown. It will still be present with a `screen-reader-only` class which allows it to be read to assistive technologies.
`indeterminate`	Boolean	`false`	When `true`, the checkbox renders a “mixed” state (shows as a “-“ in the checkbox).
`inline`	Boolean	`false`	When `true`, checkboxes will be shown on the same row rather than stacked.
`required`	Boolean	`false`	Adds the `required` attribute to the `<input>` element. NOTE: This does not perform any validation, but rather just marks the field as required.
`validationMessage`	Object		An object identifying a validation message. The object will include properties for `state` and `text`; e.g., `{ state: 'warning', text: 'This is your last warning' }`. The options for `state` are `'error'` and `'warning'`. `text` is the message shown in the validation tooltip; as with all text, it must be localized.

Callbacks

Property	Parameters	Description
`onChange`	`event`	Callback function for onChange events.

Fieldset

Properties

Property	Type	Default	Description
`legend`	String	Required	Text placed at the top of the fieldset to identify group content.
`children`	Node		A collection of elements that are to be contained within the fieldset.
`classicFieldset`	Boolean	`false`	Set to `true` to use classic fieldset styling.
`className`	String		Any custom classes to add to the `<fieldset>` element.
`disabled`	Boolean	`false`	Sets the `disabled` attribute on the `<fieldset>` element.
`formId`	String		Relates the fieldset to the parent form based on id.
`id`	String		Sets the `id` attribute on the `<fieldset>` element.
`isLegendVisible`	Boolean	`true`	Set to `false` to hide the fieldset legend. Hiding the legend only hides is visually – it is still used for accessibility reasons.
`muted`	Boolean	`false`	Set to `true` to use muted fieldset styling.
`name`	String		Sets the `name` attribute on the `<fieldset>` element.

TextArea

Properties

Property	Type	Default	Description
`className`	String		Any custom classes to add to the `<textarea>` `componentClass` element.
`id`	String		Sets the `id` attribute on the `<textarea>` `componentClass` element. If used within a `FormGroup`, the `controlId` property will be used. This property overrides that.
`inputRef`	Function		Attaches a ref to the `<input>` element.
`isResizableX`	Boolean	`false`	Sets if the textarea can be resized by the user horizontally
`isResizableY`	Boolean	`true`	Sets if the textarea can be resized by the user vertically
`required`	Boolean	`false`	Adds the `required` attribute to the `<textarea>` element. NOTE: This does not perform any validation, but rather just marks the field as required.
`size`	String	`'lg'`	Size of the `<input>` element. Options are `'lg'`, `'md'`, `'sm'`.
`validationMessageState`	String		If used in conjunction with field validation, this provides the icon next to the label. Options are `'error'`, `'warning'`.

Callbacks

Property	Parameters	Description
`onBlur`	`event`	Callback function for onBlur events.
`onFocus`	`event`	Callback function for onFocus events.

Password

Properties

Property	Type	Default	Description
`bsClass`	String	`'form-control'`	Base CSS class and prefix for the component. One should not generally change `bsClass` except to add new, non-Bootstrap CSS styles to a component.
`className`	String		Any custom classes to add to the `<input>` element.
`id`	String		Sets the `id` attribute on the `<input>` element. If used within a `FormGroup`, the `controlId` property will be used. This property overrides that.
`inputRef`	Function		Attaches a ref to the `<input>` element.
`required`	Boolean	`false`	Adds the `required` attribute to the `<input>` element. NOTE: This does not perform any validation, but rather just marks the field as required.
`size`	String	`'lg'`	Size of the `<input>` element. Options are `'lg'`, `'md'`, `'sm'`.
`validationMessageState`	String		If used in conjunction with field validation, this provides the icon next to the label. Options are `'error'`, `'warning'`.

Callbacks

Property	Parameters	Description
`onBlur`	`event`	Callback function for onBlur events.
`onFocus`	`event`	Callback function for onFocus events.

FormGroup

Properties

Property	Type	Default	Description
`bsClass`	String	`'form-group'`	Base CSS class and prefix for the component. One should not generally change `bsClass` except to add new, non-Bootstrap CSS styles to a component.
`children`	Node		Collection of React components to be placed in the form group (`ControlLabel`, `FormControl`, `FormGroup.HelpBlock`).
`controlId`	String		Sets `id` attribute on `FormControl` and `htmlFor` property on `ControlLabel`.
`required`	Boolean	`false`	Will pass the `required` property to all child components (labels and input controls).
`size`	String	`'lg'`	Size of child elements within the form group (`ControlLabel`, `FormControl`, `FormGroup.HelpBlock`). Options are `'lg'`, `'md'`, `'sm'`.
`validationMessage`	Object		An object identifying a validation message. The object will include properties for `state` and `text`; e.g., `{ state: 'warning', text: 'This is your last warning' }`. The options for `state` are `'error'` and `'warning'`. `text` is the message shown in the validation tooltip; as with all text, it must be localized.

Forms

Contents

Examples

Sizes

Checkbox

States

Inline

Fieldset

FormGroup

Required Controls

Validation States

Usage

ControlLabel

Properties

FormControl

Properties

Callbacks

Checkbox

Properties

Callbacks

Fieldset

Properties

TextArea

Properties

Callbacks

Password

Properties

Callbacks

FormGroup

Properties