Overview

The <FormControl> component renders a form control with Bootstrap styling. The <FormGroup> component wraps a form control with proper spacing, along with support for a label, help text, and validation state. To ensure accessibility, set controlId on <FormGroup>, and use <FormLabel> for the label.

Basic Form

Input States

States can be applied to all input types.

Form Feedback

Props isValid and isInvalid can be added to form controls to manually apply validation styles.

Large Inputs

Use size prop on FormControl and class label-lg to change the size of inputs and labels respectively.

Text Area

Readonly

Add the readOnly prop on an input to prevent modification of the input's value. Read-only inputs appear lighter (just like disabled inputs), but retain the standard cursor.

Readonly plain text

If you want to have readonly elements in your form styled as plain text, use the plaintext prop on FormControls to remove the default form field styling and preserve the correct margin and padding.

Layout

FormControl and FormCheck both apply display: block with width: 100% to controls, which means they stack vertically by default. Additional components and props can be used to vary this layout on a per-form basis.

Form groups

The FormGroup component is the easiest way to add some structure to forms. It provides a flexible container for grouping of labels, controls, optional help text, and form validation messaging. By default it only applies margin-bottom, but it picks up additional styles in <Form inline> as needed. Use it with fieldsets, divs, or nearly any other element.

You also add the controlId prop to accessibly wire the nested label and input together via the id.

Form grid

More complex forms can be built using the grid components. Use these for form layouts that require multiple columns, varied widths, and additional alignment options.

Form row

You may also swap <Row> for <Form.Row>, a variation of the standard grid row that overrides the default column gutters for tighter and more compact layouts.

More complex layouts can also be created with the grid system.

Horizontal form

Create horizontal forms with the grid by adding the Row to form groups and using the <Col> to specify the width of your labels and controls. Be sure to add column prop to your Form.Label as well so they’re vertically centered with their associated form controls.

At times, you maybe need to use margin or padding utilities to create that perfect alignment you need. For example, we’ve added pt-0 on our stacked radio inputs label to better align the text baseline.

Horizontal form label sizing

You can size the <FormLabel> using the column prop.

Column sizing

Grid system allows you to place any number of <Col>s within a <Row> or <Form.Row>. They'll split the available width equally between them. You may also pick a subset of your columns to take up more or less space, while the remaining <Col>s equally split the rest, with specific column classes like <Col xs={7}>.

Auto-sizing

The example below uses a flexbox utility to vertically center the contents and changes <Col> to <Col xs='auto'> so that your columns only take up as much space as needed. Put another way, the column sizes itself based on on the contents.

You can then remix that once again with size-specific column classes.

Inline forms

Use the inline prop to display a series of labels, form controls, and buttons on a single horizontal row. Form controls within forms vary slightly from their default states.

  • Controls are display: flex, collapsing any HTML white space and allowing you to provide alignment control with spacing and utilities.
  • Controls and input groups receive width: auto to override the Bootstrap default width: 100%.
  • Controls only appear inline in viewports that are at least 576px wide to account for narrow viewports on mobile devices.

You may need to manually address the width and alignment of individual form controls with spacing utilities (as shown below). Lastly, be sure to always include a <Form.Label> with each form control, even if you need to hide it from non-screenreader visitors with the srOnly prop.

Alternatives to hidden labels
Assistive technologies such as screen readers will have trouble with your forms if you don’t include a label for every input. For these inline forms, you can hide the labels using the srOnly prop. There are further alternative methods of providing a label for assistive technologies, such as the aria-label, aria-labelledby or title attribute. If none of these are present, assistive technologies may resort to using the placeholder attribute, if present, but note that use of placeholder as a replacement for other labelling methods is not advised.

Help text

Block-level help text in forms can be created using <Form.Text>. Inline help text can be flexibly implemented using any inline HTML element and utility classes like.text-muted.

Associating help text with form controls
Help text should be explicitly associated with the form control it relates to using the aria-describedby attribute. This will ensure that assistive technologies—such as screen readers—will announce this help text when the user focuses or enters the control.

Help text below inputs can be styled with <Form.Text>. This component includes display: block and adds some top margin for easy spacing from the inputs above.

Inline text can use any typical inline HTML element (be it a <small>, <span>, or something else) with nothing more than a utility class.

Disabled Forms

Add the disabled boolean attribute on an input to prevent user interactions and make it appear lighter.

Add the disabled attribute to a <fieldset> to disable all the controls within.

Caveat with anchors
By default, browsers will treat all native form controls (<input>, <select> and <button> elements) inside a <fieldset disabled> as disabled, preventing both keyboard and mouse interactions on them. However, if your form also includes <a ... className='btn btn-*'> elements, these will only be given a style of pointer-events: none. As noted in the section about disabled state for buttons (and specifically in the sub-section for anchor elements), this CSS property is not yet standardized and isn’t fully supported in Internet Explorer 10, and won’t prevent keyboard users from being able to focus or activate these links. So to be safe, use custom JavaScript to disable such links.

Cross-browser compatibility

While Bootstrap will apply these styles in all browsers, Internet Explorer 11 and below don’t fully support the disabled attribute on a <fieldset>. Use custom JavaScript to disable the fieldset in these browsers.

File browser

The custom FormFile will by default not visibly display your selected file. This requires additional JS. The recommended plugin to animate custom file input is bs-custom-file-input.

We hide the default file <input> via opacity and instead style the <label>. The button is generated and positioned with ::after. Lastly, we declare a width and height on the <input> for proper spacing for surrounding content.

Translating or customizing the strings with SCSS

The :lang() pseudo-class is used to allow for translation of the “Browse” text into other languages. Override or add entries to the $custom-file-text Sass variable with the relevant language tag and localized strings. The English strings can be customized the same way. For example, here’s how one might add a Spanish translation (Spanish’s language code is es):

$custom-file-text: (en: "Browse",es: "Elegir")

Here’s lang(es) in action on the custom file input for a Spanish translation:

You’ll need to set the language of your document (or subtree thereof) correctly in order for the correct text to be shown. This can be done using the lang attribute on the <html> element or the Content-Language HTTP header, among other methods.

Translating or customizing the strings with HTML

Bootstrap also provides a way to translate the “Browse” text in HTML with the data-browse attribute which can be added to the custom input label (example in Dutch):

Note that the data-browse attribute does not to anything unless the custom prop is set.

API

Form

import Form from `@trimbleinc/modus-react-bootstrap/Form`
NameTypeDefaultDescription
ref
ReactRef

The Form ref will be forwarded to the underlying element, which means, unless it's rendered as a composite component, it will be a DOM node, when resolved.

as
elementType
<form>
inline
boolean
false

Display the series of labels, form controls, and buttons on a single horizontal row

validated
boolean

Mark a form as having been validated. Setting it to true will toggle any validation styles on the forms elements.

bsPrefix
string
{'form'}

Form.Row

import Form.Row from `@trimbleinc/modus-react-bootstrap/Form.Row`
NameTypeDefaultDescription
as
elementType
<div>
bsPrefix required
string
'form-row'

Form.Group

import Form.Group from `@trimbleinc/modus-react-bootstrap/Form.Group`
NameTypeDefaultDescription
ref
ReactRef

The FormGroup ref will be forwarded to the underlying element. Unless the FormGroup is rendered as a composite component, it will be a DOM node, when resolved.

as
elementType
<div>
controlId
string

Sets id on <FormControl> and htmlFor on <FormGroup.Label>.

bsPrefix
string
'form-group'

Form.Label

import Form.Label from `@trimbleinc/modus-react-bootstrap/Form.Label`
NameTypeDefaultDescription
ref
ReactRef

The FormLabel ref will be forwarded to the underlying element. Unless the FormLabel is rendered as a composite component, it will be a DOM node, when resolved.

as
elementType
<label>

Set a custom element for this component

column
boolean | 'sm' | 'lg'
false

Renders the FormLabel as a <Col> component (accepting all the same props), as well as adding additional styling for horizontal forms.

htmlFor
string

Uses controlId from <FormGroup> if not explicitly specified.

srOnly
boolean
false

Hides the label visually while still allowing it to be read by assistive technologies.

bsPrefix
string
'form-label'

Form.Text

import Form.Text from `@trimbleinc/modus-react-bootstrap/Form.Text`
NameTypeDefaultDescription
ref
ReactRef

The FormText ref will be forwarded to the underlying element. Unless the FormText is rendered as a composite component, it will be a DOM node, when resolved.

as
elementType
<small>
muted
boolean

A convenience prop for add the text-muted class, since it's so commonly used here.

bsPrefix
string
'form-text'

Form.Control

import Form.Control from `@trimbleinc/modus-react-bootstrap/Form.Control`
NameTypeDefaultDescription
ref
ReactRef

The FormControl ref will be forwarded to the underlying input element, which means unless as is a composite component, it will be a DOM node, when resolved.

as
'input' | 'textarea' | 'select' | elementType
'input'

The underlying HTML element to use when rendering the FormControl.

custom
boolean

Use Bootstrap's custom form elements to replace the browser defaults

disabled
boolean

Make the control disabled

htmlSize
number

The size attribute of the underlying HTML element. Specifies the visible width in characters if as is 'input'. Specifies the number of visible options if as is 'select'.

id
string

Uses controlId from <FormGroup> if not explicitly specified.

isInvalid
boolean
false

Add "invalid" validation styles to the control and accompanying label

isValid
boolean
false

Add "valid" validation styles to the control

onChange
function

A callback fired when the value prop changes

plaintext
boolean

Render the input as plain text. Generally used along side readOnly.

readOnly
boolean

Make the control readonly

size
'sm' | 'lg'

Input size variants

type
string

The HTML input type, which is only relevant if as is 'input' (the default).

value
string | arrayOf | number
controlled by: onChange, initial prop: defaultValue

The value attribute of underlying input

bsPrefix
string
{'form-control'}
bsCustomPrefix
string
'custom'

A seperate bsPrefix used for custom controls

FormControl.Feedback

import FormControl.Feedback from `@trimbleinc/modus-react-bootstrap/FormControl.Feedback`
NameTypeDefaultDescription
as
elementType
<div>
className
string
tooltip
boolean
false

Display feedback as a tooltip.

type
'valid' | 'invalid'
'valid'

Specify whether the feedback is for valid or invalid fields

bsPrefix
never

Form.Check

import Form.Check from `@trimbleinc/modus-react-bootstrap/Form.Check`
NameTypeDefaultDescription
ref
ReactRef

The FormCheck ref will be forwarded to the underlying input element, which means it will be a DOM node, when resolved.

as
'input' | elementType
'input'

The underlying HTML element to use when rendering the FormCheck.

children
node

Provide a function child to manually handle the layout of the FormCheck's inner components.

<FormCheck>
  <FormCheck.Input isInvalid type={radio} />
  <FormCheck.Label>Allow us to contact you?</FormCheck.Label>
  <Feedback type="invalid">Yo this is required</Feedback>
</FormCheck>
custom
all(PropTypes.bool, ({ custom, id }) => custom && !id ? Error('Custom check controls require an id to work') : null, )

Use Bootstrap's custom form elements to replace the browser defaults

disabled
boolean
false

Disables the control.

feedback
node

A message to display when the input is in a validation state

feedbackTooltip
boolean
false

Display feedback as a tooltip.

id
string

A HTML id attribute, necessary for proper form accessibility. An id is recommended for allowing label clicks to toggle the check control.

This is required for custom check controls or when type="switch" due to how they are rendered.

inline
boolean
false

Groups controls horizontally with other FormChecks.

isInvalid
boolean
false

Manually style the input as invalid

isValid
boolean
false

Manually style the input as valid

label
node

Label for the control.

title
string
''

title attribute for the underlying FormCheckLabel.

type
'radio' | 'checkbox' | 'switch'
'checkbox'

The type of checkable.

bsPrefix
string
'form-check'
bsCustomPrefix
string
'custom-control'

A seperate bsPrefix used for custom controls

FormCheck.Input

import FormCheck.Input from `@trimbleinc/modus-react-bootstrap/FormCheck.Input`
NameTypeDefaultDescription
as
'input' | elementType
'input'

The underlying HTML element to use when rendering the FormCheckInput.

id
string

A HTML id attribute, necessary for proper form accessibility.

isInvalid
boolean
false

Manually style the input as invalid

isStatic
boolean

A convenience prop shortcut for adding position-static to the input, for correct styling when used without an FormCheckLabel

isValid
boolean
false

Manually style the input as valid

type
'radio' | 'checkbox'
'checkbox'

The type of checkable.

bsPrefix
string
'form-check-input'
bsCustomPrefix
string
'custom-control'

A seperate bsPrefix used for custom controls

FormCheck.Label

import FormCheck.Label from `@trimbleinc/modus-react-bootstrap/FormCheck.Label`
NameTypeDefaultDescription
htmlFor
string

The HTML for attribute for associating the label with an input

bsPrefix
string
'form-check-input'
bsCustomPrefix
string
'custom-control'

A seperate bsPrefix used for custom controls

Form.File

import Form.File from `@trimbleinc/modus-react-bootstrap/Form.File`
NameTypeDefaultDescription
as
'div' | elementType
'div'

The wrapping HTML element to use when rendering the FormFile.

children
node

Provide a function child to manually handle the layout of the FormFile's inner components.

If not using the custom prop FormFile.Label> should be before <FormFile.Input isInvalid />

<FormFile>
  <FormFile.Label>Allow us to contact you?</FormFile.Label>
  <FormFile.Input isInvalid />
  <Feedback type="invalid">Yo this is required</Feedback>
</FormFile>

If using the custom prop <FormFile.Input isInvalid /> should be before FormFile.Label>

<FormFile custom>
  <FormFile.Input isInvalid />
  <FormFile.Label>Allow us to contact you?</FormFile.Label>
  <Feedback type="invalid">Yo this is required</Feedback>
</FormFile>
custom
boolean

Use Bootstrap's custom form elements to replace the browser defaults

data-browse
string

The string for the "Browse" text label when using custom file input

disabled
boolean
false
feedback
node

A message to display when the input is in a validation state

feedbackTooltip
boolean
false

Display feedback as a tooltip.

id
string

A HTML id attribute, necessary for proper form accessibility.

inputAs
'input' | elementType
'input'

The underlying HTML element to use when rendering the FormFile.

isInvalid
boolean
false

Manually style the input as invalid

isValid
boolean
false

Manually style the input as valid

label
node
lang
all(PropTypes.string, ({ custom, lang }) => lang && !custom ? Error('`lang` can only be set when custom is `true`') : null, )

The language for the button when using custom file input and SCSS based strings

bsPrefix
string
'form-file'
bsCustomPrefix
string
'custom-file'

A seperate bsPrefix used for custom controls

FormFile.Input

import FormFile.Input from `@trimbleinc/modus-react-bootstrap/FormFile.Input`
NameTypeDefaultDescription
as
'input' | elementType
'input'

The underlying HTML element to use when rendering the FormFileInput.

id
string

A HTML id attribute, necessary for proper form accessibility.

isInvalid
boolean

Manually style the input as invalid

isValid
boolean

Manually style the input as valid

lang
string

The language for the button when using custom file input and SCSS based strings

bsPrefix
string
'form-file-input'
bsCustomPrefix
string
'custom-file-input'

A seperate bsPrefix used for custom controls

FormFile.Label

import FormFile.Label from `@trimbleinc/modus-react-bootstrap/FormFile.Label`
NameTypeDefaultDescription
data-browse
string

The string for the "Browse" text label when using custom file input

htmlFor
string

The HTML for attribute for associating the label with an input

bsPrefix
string
'form-file-input'
bsCustomPrefix
string
'custom-file-label'

A seperate bsPrefix used for custom controls