Skip to content
This repository has been archived by the owner on May 24, 2024. It is now read-only.

Terra Form Migration

Jump to bottom
Brett Jankord edited this page May 25, 2018 · 2 revisions

Below are instruction for migrating from terra-form components to the new individually packaged terra form components.

Field

The terra-form <Field /> component has been replaced with a new package, terra-form-field. Below are code samples of each. Note the difference in the imports.

// Old Field
import Field from 'terra-form/lib/Field';

<Field
  label="Old field"
  labelAttrs={{ className: 'custom-class-name' }}
  error="This field is required"
  help="Some help text"
  required
>
  // children
</Field>
// New Field
import Field from 'terra-form-field';

<Field
  label="New field"
  labelAttrs={{ className: 'custom-class-name' }}
  error="This field is required"
  help="Some help text"
  required
 >
  // children
</Field>

Prop Changes

Added Props

Prop Name Type Is Required Default Value Description
errorIcon element optional <IconError /> Error Icon to display when the input is invalid.
hideRequired bool optional false Whether or not to hide the required indicator on the label.
isLabelHidden bool optional false Whether or not the label is visible. Use this props to hide a label while still creating it on the DOM for accessibility.
showOptional bool optional false Whether or not to append the 'optional' label to a non-required field label.

Fieldset

The terra-form <Fieldset /> component has been replaced with a new package, terra-form-fieldset. Below are code samples of each. Note the difference in the imports.

// Old Fieldset
import Fieldset from 'terra-form/lib/Fieldset';

<Fieldset
  legend="Old fieldset"
  legendAttrs={{ className: 'custom-class-name' }}
  error="This field is required"
  help="Some help text"
  required
  isInline
  >
    // children
</Fieldset>
// New Fieldset
import Fieldset from 'terra-form-fieldset';

<Fieldset
  legend="Do you have any Children?"
  legendAttrs={{ className: 'custom-class-name' }}
  help="Families are eligible for family package plans"
  required
  isInline
  >
    // children
</Fieldset>

Prop Changes

Removed Props

Prop Name Type Is Required Default Value Description
error node optional null Error message for when the input is invalid.
isInline bool optional false Determines whether the fieldset is an inline fieldset.

Input

The terra-form <Input /> component has been replaced with a new package, terra-form-input. Below are code samples of each. Note the difference in the imports.

// Old Input
import Input from 'terra-form/lib/Input';

<Input
  name="foo"
  defaultValue="bar"
  required
/>
// New Input
import Input from 'terra-form-input';

<Input
  name="foo"
  defaultValue="bar"
  required
/>

Prop Changes

Added Props

Prop Name Type Is Required Default Value Description
disabled bool optional false Whether the input is disabled.
isInvalid bool optional false Whether the input is invalid.
onBlur func optional undefined Function to trigger when the input loses focus.
onFocus func optional undefined Function to trigger when the input gains focus.

TextField

The terra-form <TextField /> component can be replaced with the <InputField /> component from terra-form-input.

Below are code samples of each. Note the difference in the imports.

// Old TextField
import TextField from 'terra-form/lib/TextField';

<TextField
  type="email"
  label="Email Address"
  labelAttrs={{ className: 'custom-class-name' }}
  name="email"
  defaultValue=""
  error="This field is required"
  help="This will not be shared with outside sources"
  inputAttrs={{ className: 'custom-class-name' }}
  minLength={8}
  maxLength={75}
  required
/>
// New InputField 'TextField' examlpe
import InputField from 'terra-form-input/lib/InputField';

<InputField
  label="Email Address"
  labelAttrs={{ className: 'custom-class-name' }}
  name="email"
  defaultValue=""
  error="This field is required"
  help="This will not be shared with outside sources"
  inputAttrs={{ className: 'custom-class-name', type: 'email', minLength: 8, maxLength: 75 }}
  required
  isInvalid
/>

Prop Changes

The inputId prop is required on the <InputField />. The label prop is also required on the <InputField />. This is to help improve accessibility of the forms. If your design does not display a label, the label in the <InputField /> can be visually hidden while remaining available to screen readers by setting the isLabelHidden prop on the <InputField />.

The minLength, maxLength, name, and type props from <TextField /> have been replaced in <InputField /> with the ability to set these attributes via the inputAttrs prop.

Removed Props

Prop Name Type Is Required Default Value Description
maxLength number optional null Maximum number of characters user can input in this field.
minLength number optional null Minimum number of characters user must input in this field.
name string optional null Name of the input attribute.
type string optional 'text' The input type.

Added Props

Prop Name Type Is Required Default Value Description
errorIcon element optional Field.defaultProps.errorIcon Error Icon to display when the input is invalid.
hideRequired bool optional false Whether or not to hide the required indicator on the label.
isInvalid bool optional false Whether or not the field is invalid.
isLabelHidden bool optional false Whether or not the label is visible. Use this props to hide a label while still creating it on the DOM for accessibility.
showOptional bool optional false Whether or not to append the 'optional' label to a non-required field label.

NumberField

The terra-form <NumberField /> component can be replaced with the <InputField /> component from terra-form-input.

Below are code samples of each. Note the difference in the imports.

// Old NumberField
import NumberField from 'terra-form/lib/NumberField';

<NumberField
  label="Sales Tax Rate"
  labelAttrs={{ className: 'custom-class-name' }}
  name="sales_tax_rate"
  value={0.075}
  error="This field is required"
  help="Your county's office may have this information"
  max={1}
  min={0}
  step={0.1}
  inputAttrs={{ className: 'custom-class-name' }}
  isInline
  required
/>
// New InputField 'NumberField' examlpe
import InputField from 'terra-form-input/lib/InputField';

<InputField
  label="Sales Tax Rate"
  labelAttrs={{ className: 'custom-class-name' }}
  name="sales_tax_rate"
  value={0.075}
  error="This field is required"
  help="Your county's office may have this information"
  inputAttrs={{ className: 'custom-class-name', type: 'number', min: 0, max: 1, step: 0.1 }}
  isInline
  required
  isInvalid
  inputId="input-id"
/>

Prop Changes

The inputId prop is required on the <InputField />. The label prop is also required on the <InputField />. This is to help improve accessibility of the forms. If your design does not display a label, the label in the <InputField /> can be visually hidden while remaining available to screen readers by setting the isLabelHidden prop on the <InputField />.

The max, min, name, and step props from <NumberField /> have been replaced in <InputField /> with the ability to set these attributes via the inputAttrs prop.

Removed Props

Prop Name Type Is Required Default Value Description
max number optional null Maximum value allowed for the input.
min number optional null Minimum value allowed for the input.
name string optional null Name of the input attribute.
step number optional null Incremental steps for increasing and descreasing the value.

Added Props

Prop Name Type Is Required Default Value Description
errorIcon element optional Field.defaultProps.errorIcon Error Icon to display when the input is invalid.
hideRequired bool optional false Whether or not to hide the required indicator on the label.
isInvalid bool optional false Whether or not the field is invalid.
isLabelHidden bool optional false Whether or not the label is visible. Use this props to hide a label while still creating it on the DOM for accessibility.
showOptional bool optional false Whether or not to append the 'optional' label to a non-required field label.

Textarea

The terra-form <Textarea /> component has been replaced with a new package, terra-form-textarea. Below are code samples of each. Note the difference in the imports.

// Old Textarea
import Textarea from 'terra-form/lib/Textarea';

<Textarea
  name="description"
  value="Some content in a textarea"
  required
 />
// New Textarea
import Textarea from 'terra-form-textarea';

<Textarea
  name="description"
  value="Some content in a textarea"
  required
 />

Prop Changes

Added Props

Prop Name Type Is Required Default Value Description
disabled bool optional false Whether the textarea is disabled.
isAutoResizable bool optional false Whether the textarea can be auto-resized vertically.
isInvalid bool optional false Whether the form is invalid.
onFocus func optional none Function to trigger when user focuses on this textarea.
rows number optional null Value to set for the rows attribute of the textarea. This takes presidence over size when setting the height of the textarea.
size string optional 'small' The size of the textarea. Sizes the textarea by setting the rows attribute to the number corresponding to this value.

TextareaField

The terra-form <TextareaField /> component has been replaced with a new package, terra-form-textarea. Below are code samples of each. Note the difference in the imports.

// Old TextareaField
import TextareaField from 'terra-form/lib/TextareaField';

<TextareaField
  name="description"
  label="Description"
  labelAttrs={{ className: 'custom-class-name' }}
  error="This field is required"
  cols={20}
  rows={10}
  value="Some content in a textarea"
  inputAttrs={{ className: 'custom-class-name' }}
  required
/>
// New TextareaField
import TextareaField from 'terra-form-textarea/lib/TextareaField';

<TextareaField
  name="description"
  label="Description"
  labelAttrs={{ className: 'custom-class-name' }}
  error="This field is required"
  value="Some content in a textarea"
  inputAttrs={{ className: 'custom-class-name', cols: '20', rows: '10' }}
  required
  isInline
  inputId="textarea-id"
/>

Prop Changes

The inputId prop is required on the <TextareaField />. The label prop is also required on the <TextareaField />. This is to help improve accessibility of the forms. If your design does not display a label, the label in the <TextareaField /> can be visually hidden while remaining available to screen readers by setting the isLabelHidden prop on the <TextareaField />.

The minLength, maxLength, name, and cols, rows props from <TextareaField /> have been replaced in <InputField /> with the ability to set these attributes via the inputAttrs prop.

Removed Props

Prop Name Type Is Required Default Value Description
cols number optional null How many columns the textarea should have.
maxLength number optional null Maximum number of characters user can input in this field.
minLength number optional null Minimum number of characters user must input in this field.
name string optional null Name of the input attribute.
rows number optional null How many rows the textarea should have.

Added Props

Prop Name Type Is Required Default Value Description
errorIcon element optional Field.defaultProps.errorIcon Error Icon to display when the input is invalid.
hideRequired bool optional false Whether or not to hide the required indicator on the label.
isInvalid bool optional false Whether or not the field is invalid.
isLabelHidden bool optional false Whether or not the label is visible. Use this props to hide a label while still creating it on the DOM for accessibility.
showOptional bool optional false Whether or not to append the 'optional' label to a non-required field label.

Control (Checkbox)

The terra-form <Control /> component can be replaced with the <Checkbox /> component from terra-form-checkbox.

Below are code samples of each. Note the difference in the imports.

// Old Control
import Control from 'terra-form/lib/Control';

<Control
  type="checkbox"
  defaultChecked={true}
  id="form-checkbox1" 
  inputAttrs={{ className: 'custom-class-name' }}
  labelText="Do you want to improve health care?"
  labelTextAttrs={{ className: 'custom-class-name' }}
  name="improve-health-care"
  onChange={() => { }}
  value="hc"
  isInline 
/>
// New Checkbox 'Control' examlpe
import Checkbox from 'terra-form-checkbox';

<Checkbox
  defaultChecked={true}
  id="form-checkbox2" 
  inputAttrs={{ className: 'custom-class-name' }}
  labelText="Do you want to improve health care?"
  labelTextAttrs={{ className: 'custom-class-name' }}
  name="improve-health-care"
  onChange={() => { }}
  value="hc"
  isInline 
/>

Prop Changes

The type prop from the Control component is no longer needed on the Checkbox component as the type is defaulted to checkbox in the Checkbox component.

Removed Props

Prop Name Type Is Required Default Value Description
type string optional null The input type.

Added Props

Prop Name Type Is Required Default Value Description
disabled bool optional false Whether the checkbox element is disabled.
isLabelHidden bool optional false Whether the label is hidden.
onBlur func optional undefined Function to trigger when focus is lost from the checkbox.
onFocus func optional undefined Function to trigger when user focuses on the checkbox.

Control (Radio)

The terra-form <Control /> component can be replaced with the <Radio /> component from terra-form-radio.

Below are code samples of each. Note the difference in the imports.

// Old Control
import Control from 'terra-form/lib/Control';

<Control
  type="radio"
  defaultChecked={true}
  id="form-radio1" 
  inputAttrs={{ className: 'custom-class-name' }}
  labelText="Do you want to improve health care?"
  labelTextAttrs={{ className: 'custom-class-name' }}
  name="improve-health-care"
  onChange={() => { }}
  value="hc"
  isInline 
/>
// New Radio 'Control' examlpe
import Radio from 'terra-form-radio';

<Radio
  defaultChecked={true}
  id="form-radio2" 
  inputAttrs={{ className: 'custom-class-name' }}
  labelText="Do you want to improve health care?"
  labelTextAttrs={{ className: 'custom-class-name' }}
  name="improve-health-care"
  onChange={() => { }}
  value="hc"
  isInline 
/>

Prop Changes

The type prop from the Control component is no longer needed on the Radio component as the type is defaulted to radio in the Radio component.

Removed Props

Prop Name Type Is Required Default Value Description
type string optional null The input type.

Added Props

Prop Name Type Is Required Default Value Description
disabled bool optional false Whether the checkbox element is disabled.
isLabelHidden bool optional false Whether the label is hidden.
onBlur func optional undefined Function to trigger when focus is lost from the checkbox.
onFocus func optional undefined Function to trigger when user focuses on the checkbox.

Terra Form Select Upgrade Guide

Changes from 3.0 to 4.0

Breaking Changes

  • Removed boundingRef
  • Removed isPlaceholderHidden
  • Removed name
  • Removed required
  • Removed releaseFocus
  • Removed requestFocus
  • Removed the event and name from onChange callback
  • Removed isSelected from Select.Option
  • Removed children from Select.Option
  • Removed and renamed specific CSS Custom Properties

New props

  • Added dropdownAttrs
  • Added noResultContent
  • Added onDeselect
  • Added onSelect
  • Added onSearch
  • Added optionFilter
  • Added placeholder
  • Added variant
  • Added Select.OptGroup

Changes to onChange

The onChange callback has been changed to return only the value. To uplift remove the event and name parameter from the callback.

onChange(event, value, name) -> onChange(value)

import React from 'react';
import Select from 'terra-form-select';

class Default extends React.Component {
  constructor() {
    super();

    this.state = { value: 'blue' };
    this.handleChange = this.handleChange.bind(this);
  }

-  handleChange(event, value, name) {
+  handleChange(value) {
    this.setState({ value });
  }

  render() {
    return (
      <Select onChange={this.handleChange} value={this.state.value}>
        <Select.Option value="blue" display="Blue" />
        <Select.Option value="green" display="Green" />
        <Select.Option value="purple" display="Purple" />
      </Select>
    );
  }
}

export default Default;

Changes to isPlaceholderHidden

The isPlaceholderHidden hidden prop has been removed. To uplift remove this prop declaration.

- <Select isPlaceholderHidden>
+ <Select>
    <Select.Option value="blue" display="Blue" />
    <Select.Option value="green" display="Green" />
    <Select.Option value="purple" display="Purple" />
  </Select>

If a placeholder option is necessary it can be added to the list of options.

<Select>
  <Select.Option value="" display="-- Select --" />
  <Select.Option value="blue" display="Blue" />
  <Select.Option value="green" display="Green" />
  <Select.Option value="purple" display="Purple" />
</Select>

Changes to name and required

The name and required props have been removed. Terra recommends handling form submissions and validations with react-final-form. To uplift remove these prop declarations.

Changes to releaseFocus and releaseFocus

The releaseFocus and releaseFocus props have been removed. It is no longer necessary for the consumer to manage the focus state. To uplift remove these prop declarations.

Changes to boundingRef

The boundingRef prop has been removed. The dropdown has been updated to never expand outside of the available window space. To uplift remove these prop declarations.

Changes to Select.Option

The children and isSelected props have been removed. To uplift remove isSelected prop declarations and move children into display.

Children should be placed inside of display.

- <Select.Option value="value">Display</Select.Option>
+ <Select.Option value="value" display="Display" />

The selection state of each option is managed by the Select. The selected option values should be supplied to the Select's defaultValue or value.

Changes to CSS Custom Properties

CSS Custom Properties have been updated to follow naming conventions. A CSS property should define the component, state, and property it controls.

Select icons have been updated to be theme-able in CSS. This means the entire icon will need to be changed to alter color.

Renamed

Previous Updated
--terra-select-disabled-font-color --terra-select-disabled-color
--terra-select-focus-animation-background --terra-select-focus-background-image
--terra-select-focus-background-start --terra-select-background-size
--terra-select-focus-transition-timing --terra-select-focus-transition-timing-function
--terra-select-focus-animation-size --terra-select-focus-background-size
--terra-select-focus-box-shadow-rtl --terra-select-focus-box-shadow
--terra-select-focus-box-shadow-ltr --terra-select-focus-box-shadow
--terra-select-input-border-color --terra-select-border-color
--terra-select-input-hover-border-color --terra-select-hover-border-color
--terra-select-input-focus-border-color --terra-select-focus-border-color
--terra-select-default-option-color --terra-select-option-color
--terra-select-default-option-font-style --terra-select-option-font-style
--terra-select-input-text-color --terra-select-color
--terra-select-invalid-focus-animation-background --terra-select-invalid-background-image
--terra-select-invalid-focus-animation-size --terra-select-invalid-focus-background-size
--terra-select-invalid-focus-box-shadow-ltr --terra-select-invalid-focus-box-shadow
--terra-select-invalid-focus-box-shadow-rtl --terra-select-invalid-focus-box-shadow
--terra-select-option-font-color --terra-select-option-color
--terra-select-option-selected-font-color --terra-select-option-selected-color
--terra-select-option-selected-color --terra-select-option-selected-background-color
--terra-select-option-hover-color --terra-select-option-active-color

Removed

  • --terra-select-arrow-margin
  • --terra-select-arrow-color
  • --terra-select-disabled-arrow-color
  • --terra-select-input-border-color
  • --terra-select-input-padding
  • --terra-select-invalid-arrow-color
  • --terra-select-menu-blur-background-color
  • --terra-select-menu-bottom-padding
  • --terra-select-menu-background-color
  • --terra-select-menu-border-raidus
  • --terra-select-menu-blur
  • --terra-select-menu-box-shadow-ltr
  • --terra-select-menu-box-shadow-rtl

Added

  • --terra-select-border
  • --terra-select-bottom-padding
  • --terra-select-left-padding
  • --terra-select-right-padding
  • --terra-select-top-padding
  • --terra-select-arrow-background
  • --terra-select-invalid-arrow-background
  • --terra-select-menu-padding
  • --terra-select-menu-margin
  • --terra-select-arrow-background
  • --terra-select-dropdown-background-color
  • --terra-select-dropdown-border
  • --terra-select-dropdown-border-radius
  • --terra-select-dropdown-box-shadow
  • --terra-select-dropdown-above-box-shadow
  • --terra-select-option-icon-background
  • --terra-select-option-icon-active-background
  • --terra-select-option-icon-pressed-background
  • --terra-select-option-selected-active-background-color
  • --terra-select-option-icon-height
  • --terra-select-tag-background
  • --terra-select-tag-border-radius
  • --terra-select-tag-font-size
  • --terra-select-tag-line-height
  • --terra-select-tag-margin-right
  • --terra-select-tag-margin-top
  • --terra-select-tag-display-border-bottom
  • --terra-select-tag-display-padding
  • --terra-select-tag-deselect-background
  • --terra-select-tag-deselect-border-bottom
  • --terra-select-tag-deselect-font-size
  • --terra-select-tag-deselect-padding
  • --terra-select-tag-deselect-hover-background
  • --terra-select-tag-deselect-hover-border-bottom-hover
  • --terra-select-tag-icon-background
  • --terra-select-tag-icon-height
  • --terra-select-tag-icon-width

New dropdownAttrs

The new prop for dropdownAttrs spreads custom html attributes onto the dropdown menu. Examples include classnames and inline styles.

<Select dropdownAttrs={{ style: { maxHeight: '300px' } }}>
  <Select.Option value="blue" display="Blue" />
  <Select.Option value="green" display="Green" />
  <Select.Option value="purple" display="Purple" />
</Select>

New noResultContent

The noResultContent prop displays custom content when no search results are found.

<Select noResultContent="No colors were found.">
  <Select.Option value="blue" display="Blue" />
  <Select.Option value="green" display="Green" />
  <Select.Option value="purple" display="Purple" />
</Select>

New onDeselect

The onDeselect prop is called when an option is deselected. The callback will return the value of the deselected option.

New onSelect

The onSelect prop is called when an option is selected. The callback will return the value of the selected option.

New onSearch

The onSearch prop is called when a search is invoked. The callback will return the value of the search input.

New optionFilter

The optionFilter prop is called for each option when the search input changes allowing a custom filter.

By default the Select filters all options that contain the search string within the display. In the following example the Select is instead filtered by options that start with the string.

<Select optionFilter={(input, option) => option.props.display.startsWith(input)}>
  <Select.Option value="blue" display="Blue" />
  <Select.Option value="green" display="Green" />
  <Select.Option value="purple" display="Purple" />
</Select>

New placeholder

The placeholder prop sets the placeholder text.

<Select placeholder="Select a color">
  <Select.Option value="blue" display="Blue" />
  <Select.Option value="green" display="Green" />
  <Select.Option value="purple" display="Purple" />
</Select>

New variant

The variant prop sets the display and behavior of the Select. Options include:

Variant Description
default Allows only a single selection.
search Allows only a single selection. Provides a searchable list of options.
combobox Allows only a single selection or free text entry. The select will act as a standard input with a drop down menu that provides an optional set of selections to choose from. The options will filter as a user types into the input. Selecting a preexisting option from the dropdown is optional; the user can enter a new value.
multiple Allows multiple selections. The user may choose multiple options from the dropdown. Each selected option can be deselected either by clicking the option again in the drop down or by clicking the x icon next to the option in the list of selected options.
tag Allows multiple selections or free text entries. The user may choose multiple options from the dropdown or enter a custom free text entry.

New Select.OptGroup

An OptGroup creates a grouping of options into a labeled section.

<Select>
  <Select.OptGroup label="Shade of blue">
    <Select.Option value="blue" display="Blue" />
    <Select.Option value="cyan" display="Cyan" />
    <Select.Option value="teal" display="Teal" />
    <Select.Option value="azul" display="Azul" />
    <Select.Option value="aqua" display="Aqua" />
  </Select.OptGroup>
</Select>
Clone this wiki locally