Components

#Forms FormGroup, FormControl, ControlLabel

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 <ControlLabel> for the label.

Validation is based on string length.
class FormExample extends React.Component {
  constructor(props, context) {
    super(props, context);

    this.handleChange = this.handleChange.bind(this);

    this.state = {
      value: ''
    };
  }

  getValidationState() {
    const length = this.state.value.length;
    if (length > 10) return 'success';
    if (length > 5) return 'warning';
    if (length > 0) return 'error';
    return null;
  }

  handleChange(e) {
    this.setState({ value: e.target.value });
  }

  render() {
    return (
      <form>
        <FormGroup
          controlId="formBasicText"
          validationState={this.getValidationState()}
        >
          <ControlLabel>Working example with validation</ControlLabel>
          <FormControl
            type="text"
            value={this.state.value}
            placeholder="Enter text"
            onChange={this.handleChange}
          />
          <FormControl.Feedback />
          <HelpBlock>Validation is based on string length.</HelpBlock>
        </FormGroup>
      </form>
    );
  }
}

render(<FormExample />);

The <FormControl> component directly renders the <input> or other specified component. If you need to access the value of an uncontrolled <FormControl>, attach a ref to it as you would with an uncontrolled input, then call ReactDOM.findDOMNode(ref) to get the DOM node. You can then interact with that node as you would with any other uncontrolled input.

If your application contains a large number of form groups, we recommend building a higher-level component encapsulating a complete field group that renders the label, the control, and any other necessary components. We don't provide this out-of-the-box, because the composition of those field groups is too specific to an individual application to admit a good one-size-fits-all solution.

#Props

#FormGroup[source]

NameTypeDefaultDescription
controlId
string

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

validationState
one of: 'success', 'warning', 'error', null
bsSize
one of: "lg", "large", "sm", "small"

Component size variations.

bsClass
string
'form-group'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#FormControl[source]

NameTypeDefaultDescription
componentClass
elementType
'input'

You can use a custom element type for this component.

type
string

Only relevant if componentClass is 'input'.

id
string

Uses controlId from <FormGroup> if not explicitly specified.

inputRef
function

Attaches a ref to the <input> element. Only functions can be used here.

<FormControl inputRef={ref => { this.input = ref; }} />
bsSize
one of: "sm", "small", "lg", "large"

Component size variations.

bsClass
string
'form-control'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#ControlLabel[source]

NameTypeDefaultDescription
htmlFor
string

Uses controlId from <FormGroup> if not explicitly specified.

srOnly
boolean
false
bsClass
string
'control-label'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#Supported controls Checkbox, Radio, FormControl.Static, HelpBlock

Examples of standard form controls supported in an example form layout, using a custom <FieldGroup> component. Use <FormControl> for <input>, <textarea>, and <select>. Use <Checkbox> and <Radio> for checkboxes and radios respectively, optionally with inline to render multiple on the same line. Use <FormControl.Static> for static text.

Example block-level help text here.

email@example.com

function FieldGroup({ id, label, help, ...props }) {
  return (
    <FormGroup controlId={id}>
      <ControlLabel>{label}</ControlLabel>
      <FormControl {...props} />
      {help && <HelpBlock>{help}</HelpBlock>}
    </FormGroup>
  );
}

const formInstance = (
  <form>
    <FieldGroup
      id="formControlsText"
      type="text"
      label="Text"
      placeholder="Enter text"
    />
    <FieldGroup
      id="formControlsEmail"
      type="email"
      label="Email address"
      placeholder="Enter email"
    />
    <FieldGroup id="formControlsPassword" label="Password" type="password" />
    <FieldGroup
      id="formControlsFile"
      type="file"
      label="File"
      help="Example block-level help text here."
    />

    <Checkbox checked readOnly>
      Checkbox
    </Checkbox>
    <Radio checked readOnly>
      Radio
    </Radio>

    <FormGroup>
      <Checkbox inline>1</Checkbox> <Checkbox inline>2</Checkbox>{' '}
      <Checkbox inline>3</Checkbox>
    </FormGroup>
    <FormGroup>
      <Radio name="radioGroup" inline>
        1
      </Radio>{' '}
      <Radio name="radioGroup" inline>
        2
      </Radio>{' '}
      <Radio name="radioGroup" inline>
        3
      </Radio>
    </FormGroup>

    <FormGroup controlId="formControlsSelect">
      <ControlLabel>Select</ControlLabel>
      <FormControl componentClass="select" placeholder="select">
        <option value="select">select</option>
        <option value="other">...</option>
      </FormControl>
    </FormGroup>
    <FormGroup controlId="formControlsSelectMultiple">
      <ControlLabel>Multiple select</ControlLabel>
      <FormControl componentClass="select" multiple>
        <option value="select">select (multiple)</option>
        <option value="other">...</option>
      </FormControl>
    </FormGroup>

    <FormGroup controlId="formControlsTextarea">
      <ControlLabel>Textarea</ControlLabel>
      <FormControl componentClass="textarea" placeholder="textarea" />
    </FormGroup>

    <FormGroup>
      <ControlLabel>Static text</ControlLabel>
      <FormControl.Static>email@example.com</FormControl.Static>
    </FormGroup>

    <Button type="submit">Submit</Button>
  </form>
);

render(formInstance);

#Props

#Checkbox[source]

NameTypeDefaultDescription
inline
boolean
false
disabled
boolean
false
title
string
''
validationState
one of: 'success', 'warning', 'error', null

Only valid if inline is not set.

inputRef
function

Attaches a ref to the <input> element. Only functions can be used here.

<Checkbox inputRef={ref => { this.input = ref; }} />
bsClass
string
'checkbox'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#Radio[source]

NameTypeDefaultDescription
inline
boolean
false
disabled
boolean
false
title
string
''
validationState
one of: 'success', 'warning', 'error', null

Only valid if inline is not set.

inputRef
function

Attaches a ref to the <input> element. Only functions can be used here.

<Radio inputRef={ref => { this.input = ref; }} />
bsClass
string
'radio'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#FormControl.Static[source]

NameTypeDefaultDescription
componentClass
elementType
'p'

You can use a custom element type for this component.

bsClass
string
'form-control-static'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#HelpBlock[source]

NameTypeDefaultDescription
bsClass
string
'help-block'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#Form layout Form

#Inline forms

Use <Form inline> instead of <form>. JSX strips whitespace between lines, so you will need to manually add spaces. Additionally, Bootstrap assigns inline form controls width: auto by default, so you may need to set custom widths.

<Form inline>
  <FormGroup controlId="formInlineName">
    <ControlLabel>Name</ControlLabel>{' '}
    <FormControl type="text" placeholder="Jane Doe" />
  </FormGroup>{' '}
  <FormGroup controlId="formInlineEmail">
    <ControlLabel>Email</ControlLabel>{' '}
    <FormControl type="email" placeholder="jane.doe@example.com" />
  </FormGroup>{' '}
  <Button type="submit">Send invitation</Button>
</Form>;

#Horizontal forms

Use <Form horizontal> instead of <form>, then use <Col>s to align labels and controls. Do not use <Row> here, as <FormGroup> will already serve as a grid row in a horizontal form.

<Form horizontal>
  <FormGroup controlId="formHorizontalEmail">
    <Col componentClass={ControlLabel} sm={2}>
      Email
    </Col>
    <Col sm={10}>
      <FormControl type="email" placeholder="Email" />
    </Col>
  </FormGroup>

  <FormGroup controlId="formHorizontalPassword">
    <Col componentClass={ControlLabel} sm={2}>
      Password
    </Col>
    <Col sm={10}>
      <FormControl type="password" placeholder="Password" />
    </Col>
  </FormGroup>

  <FormGroup>
    <Col smOffset={2} sm={10}>
      <Checkbox>Remember me</Checkbox>
    </Col>
  </FormGroup>

  <FormGroup>
    <Col smOffset={2} sm={10}>
      <Button type="submit">Sign in</Button>
    </Col>
  </FormGroup>
</Form>;

#Props

#Form[source](only needed for horizontal or inline forms)

NameTypeDefaultDescription
horizontal
boolean
false
inline
boolean
false
componentClass
elementType
'form'

You can use a custom element type for this component.

bsClass
string
'form'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#Input groupsInputGroup, InputGroup.Addon, InputGroup.Button

#Input add-ons

Wrap your form control in an <InputGroup>, then use for normal add-ons and for button add-ons. Exotic configurations may require CSS on your side.

@
.00
$.00
<form>
  <FormGroup>
    <InputGroup>
      <InputGroup.Addon>@</InputGroup.Addon>
      <FormControl type="text" />
    </InputGroup>
  </FormGroup>
  <FormGroup>
    <InputGroup>
      <FormControl type="text" />
      <InputGroup.Addon>.00</InputGroup.Addon>
    </InputGroup>
  </FormGroup>
  <FormGroup>
    <InputGroup>
      <InputGroup.Addon>$</InputGroup.Addon>
      <FormControl type="text" />
      <InputGroup.Addon>.00</InputGroup.Addon>
    </InputGroup>
  </FormGroup>

  <FormGroup>
    <InputGroup>
      <FormControl type="text" />
      <InputGroup.Addon>
        <Glyphicon glyph="music" />
      </InputGroup.Addon>
    </InputGroup>
  </FormGroup>

  <FormGroup>
    <InputGroup>
      <InputGroup.Button>
        <Button>Before</Button>
      </InputGroup.Button>
      <FormControl type="text" />
    </InputGroup>
  </FormGroup>
  <FormGroup>
    <InputGroup>
      <FormControl type="text" />
      <DropdownButton
        componentClass={InputGroup.Button}
        id="input-dropdown-addon"
        title="Action"
      >
        <MenuItem key="1">Item</MenuItem>
      </DropdownButton>
    </InputGroup>
  </FormGroup>

  <FormGroup>
    <InputGroup>
      <InputGroup.Addon>
        <input type="radio" aria-label="..." />
      </InputGroup.Addon>
      <FormControl type="text" />
    </InputGroup>
  </FormGroup>
  <FormGroup>
    <InputGroup>
      <InputGroup.Addon>
        <input type="checkbox" aria-label="..." />
      </InputGroup.Addon>
      <FormControl type="text" />
    </InputGroup>
  </FormGroup>
</form>;

#Input sizes

Use bsSize on <FormGroup> or <InputGroup> to change the size of inputs. It also works with add-ons and most other options.

<form>
  <FormGroup bsSize="large">
    <FormControl type="text" placeholder="Large text" />
  </FormGroup>
  <FormGroup>
    <FormControl type="text" placeholder="Normal text" />
  </FormGroup>
  <FormGroup bsSize="small">
    <FormControl type="text" placeholder="Small text" />
  </FormGroup>
</form>;

#Props

#InputGroup[source]

NameTypeDefaultDescription
bsSize
one of: "lg", "large", "sm", "small"

Component size variations.

bsClass
string
'input-group'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#InputGroup.Addon[source]

NameTypeDefaultDescription
bsClass
string
'input-group-addon'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#InputGroup.Button[source]

NameTypeDefaultDescription
bsClass
string
'input-group-btn'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.

#Validation statesFormControl.Feedback

Set validationState to one of 'success', 'warning' or 'error' to show validation state. Set validationState to null (or undefined) to hide validation state. Add <FormControl.Feedback> for a feedback icon when validation state is set.

Help text with validation state.
@
@
@
<form>
  <FormGroup controlId="formValidationSuccess1" validationState="success">
    <ControlLabel>Input with success</ControlLabel>
    <FormControl type="text" />
    <HelpBlock>Help text with validation state.</HelpBlock>
  </FormGroup>

  <FormGroup controlId="formValidationWarning1" validationState="warning">
    <ControlLabel>Input with warning</ControlLabel>
    <FormControl type="text" />
  </FormGroup>

  <FormGroup controlId="formValidationError1" validationState="error">
    <ControlLabel>Input with error</ControlLabel>
    <FormControl type="text" />
  </FormGroup>

  <FormGroup controlId="formValidationNull" validationState={null}>
    <ControlLabel>Input with no validation state</ControlLabel>
    <FormControl type="text" />
  </FormGroup>

  <FormGroup controlId="formValidationSuccess2" validationState="success">
    <ControlLabel>Input with success and feedback icon</ControlLabel>
    <FormControl type="text" />
    <FormControl.Feedback />
  </FormGroup>

  <FormGroup controlId="formValidationWarning2" validationState="warning">
    <ControlLabel>Input with warning and feedback icon</ControlLabel>
    <FormControl type="text" />
    <FormControl.Feedback />
  </FormGroup>

  <FormGroup controlId="formValidationError2" validationState="error">
    <ControlLabel>Input with error and feedback icon</ControlLabel>
    <FormControl type="text" />
    <FormControl.Feedback />
  </FormGroup>

  <FormGroup controlId="formValidationSuccess3" validationState="success">
    <ControlLabel>Input with success and custom feedback icon</ControlLabel>
    <FormControl type="text" />
    <FormControl.Feedback>
      <Glyphicon glyph="music" />
    </FormControl.Feedback>
  </FormGroup>

  <FormGroup controlId="formValidationWarning3" validationState="warning">
    <ControlLabel>Input group with warning</ControlLabel>
    <InputGroup>
      <InputGroup.Addon>@</InputGroup.Addon>
      <FormControl type="text" />
    </InputGroup>
    <FormControl.Feedback />
  </FormGroup>

  <Form componentClass="fieldset" horizontal>
    <FormGroup controlId="formValidationError3" validationState="error">
      <Col componentClass={ControlLabel} xs={3}>
        Input with error
      </Col>
      <Col xs={9}>
        <FormControl type="text" />
        <FormControl.Feedback />
      </Col>
    </FormGroup>

    <FormGroup controlId="formValidationSuccess4" validationState="success">
      <Col componentClass={ControlLabel} xs={3}>
        Input group with success
      </Col>
      <Col xs={9}>
        <InputGroup>
          <InputGroup.Addon>@</InputGroup.Addon>
          <FormControl type="text" />
        </InputGroup>
        <FormControl.Feedback />
      </Col>
    </FormGroup>
  </Form>

  <Form componentClass="fieldset" inline>
    <FormGroup controlId="formValidationWarning4" validationState="warning">
      <ControlLabel>Input with warning</ControlLabel>{' '}
      <FormControl type="text" />
      <FormControl.Feedback />
    </FormGroup>{' '}
    <FormGroup controlId="formValidationError4" validationState="error">
      <ControlLabel>Input group with error</ControlLabel>{' '}
      <InputGroup>
        <InputGroup.Addon>@</InputGroup.Addon>
        <FormControl type="text" />
      </InputGroup>
      <FormControl.Feedback />
    </FormGroup>
  </Form>

  <Checkbox validationState="success">Checkbox with success</Checkbox>
  <Radio validationState="warning">Radio with warning</Radio>
  <Checkbox validationState="error">Checkbox with error</Checkbox>

  {/* This requires React 15's <span>-less spaces to be exactly correct. */}
  <FormGroup validationState="success">
    <Checkbox inline>Checkbox</Checkbox> <Checkbox inline>with</Checkbox>{' '}
    <Checkbox inline>success</Checkbox>
  </FormGroup>
</form>;

#Props

#FormControl.Feedback[source]

NameTypeDefaultDescription
bsClass
string
'form-control-feedback'

Base CSS class and prefix for the component. Generally one should only change bsClass to provide new, non-Bootstrap, CSS styles for a component.