Starbucks React Pattern Library

Field

Notes

A form field with validation support.

Props

childrennode*
Text or element(s) used as children of the field's label element.
classNamestring
containerPropsobject
Props applied to the field's outer container.
customFieldStatusbool
A flag indicating that the field uses a custom element to display field status and should not wrap error messages in a FieldStatus component.
defaultValuestring
displayStatusbool
A flag indicating that the field should display its error message irrespective of the field's error status. If set to true, the error message will display no matter what. If set to false, it will never display.
errorbool
A flag indicating that the field is in an error state.
errorMessagenode
A message to display when the field is in an error state. Wrapped in a FieldStatus component by default.
floatLabelActiveTextstring
Optional text used as field's label element when the the field is in an active state.
floatLabelIdstring
Optional id to be set on the associated label, can be useful for creating accessibility relationships between elements
floatLabelVisiblebool[true]
Set to false to only show the label when the field does not have a value
idstring*
inputAddonnode
An additional element rendered within the field after the input element. Used to apply extra buttons and labels on the edges of fields.
namestring
onChangefunc
onBlurfunc
onFocusfunc
requiredbool
typestring['text']
valuestring

Field - Toggle error prop to true to see error message

<div>
  <div className="p3">
    <Field
      id='email'
      error={ false }
      floatLabelActiveText="Email Address"
      errorMessage='Please enter a valid email address'
    >
      Enter Email Address
    </Field>
  </div>
  <div className="bg-white p3">
    <Field
      id='email_white-bg'
      error={ false }
      floatLabelActiveText="Email Address"
      errorMessage='Please enter a valid email address'
    >
      Enter Email Address
    </Field>
  </div>
</div>

<div>
  <div className="p3">
    <Field
      id='email'
      error={ false }
      floatLabelActiveText="Email Address"
      errorMessage='Please enter a valid email address'
    >
      Enter Email Address
    </Field>
  </div>
  <div className="bg-white p3">
    <Field
      id='email_white-bg'
      error={ false }
      floatLabelActiveText="Email Address"
      errorMessage='Please enter a valid email address'
    >
      Enter Email Address
    </Field>
  </div>
</div>

Mutliple fields arranged vertically

<div>
  <Field id='firstNameStacked' className='mb2'>First Name</Field>

  <Field id='lastNameStacked' className='mb2'>Last Name</Field>

  <Field 
    id='emailStacked'
    error={ true }
    errorMessage='Please enter a valid email address'
  >
    Email Address
  </Field>
</div>

<div>
  <Field id='firstNameStacked' className='mb2'>First Name</Field>

  <Field id='lastNameStacked' className='mb2'>Last Name</Field>

  <Field 
    id='emailStacked'
    error={ true }
    errorMessage='Please enter a valid email address'
  >
    Email Address
  </Field>
</div>

FieldStatus

Notes

Displays validation messages for form fields. Used by default in the Field component.

Props

childrennode
classNamestring
errorbool
Current error status. Pass true to mark as an error, false to mark that the field is valid, or leave undefined for an indeterminate default state.

<FieldStatus error={ true }>
  Please enter a valid email address
</FieldStatus>

<FieldStatus error={ true }>
  Please enter a valid email address
</FieldStatus>

FormContainer

Notes

A wrapping component for managing field state and form submission. FormContainer creates no UI, but passes it's props on to its child, which is typically a form element. It receives a fields configuration prop, and decorates it as fieldsState. Each field gains dynamic error, wasChanged, and wasValid properties. A nested input object maintains properties for the field's associated input. i.e. id, name, required, value, onChange, onBlur. Every change event in the child form triggers a re-render with updated field state (including validation).

Props

childrennode[<div />]
fields
shape {
requiredbool
validatorfunc
inputobject
}
[{}]
An object to configure fields using input names as the key.

Validation can specified for each field in the following ways:
- required: true (default) uses the validateExistence as validator
- required: false no validation
- validator A custom validator function
focusOnSubmitErrorbool
Set focus on the first invalid input during submittals.
onErrorfunc[() => {}]
Callback for invalid form submittals. Invoked with validation results for invalid fields.
onFieldsStateChangefunc[() => {}]
Callback for when the field state has changed. Invoked with fieldsState, oldFieldsState
onFieldUpdateFromEventfunc[() => {}]
Callback for a when field has been updated from a dom event. Invoked with the event, fieldState.
onSubmitfunc[() => {}]
Callback for valid form submittals. Invoked with form data.
focusOnInvalidAfterAnimationbool
Forces focusOnFirstInvalid to wait for animations so that focus can be properly applied.

const ExampleForm = ({ fields, isValid, onSubmit }) => {
  /**
   *
   * Example of a field state object:
   * {
   *   error: true, // true when previously valid or the input is blurred
   *   wasBlurred: true,
   *   wasChanged: true,
   *   wasValid: true,
   *   input: {
   *     id: "fieldOne",
   *     name: "fieldOne",
   *     onBlur: handleBlur,
   *     onChange: handleChange,
   *     required: true,
   *     value: ""
   *   }
   * }
  */
  // console.log('fieldState objects:', fields);
  // console.log('fields are valid', isValid);

  return (
    <form onSubmit={ onSubmit } noValidate>
      <Field
        { ...fields.fieldOne.input }
        error={ shouldDisplayError(fields.fieldOne)}
        errorMessage='Please enter a value'
        className='mb2'>
          fieldOne (required)
      </Field>
      <Field
        { ...fields.fieldTwo.input }
        className='mb2'>
          fieldTwo (optional)
      </Field>
      <Field
        { ...fields.fieldThree.input }
        error={ shouldDisplayError(fields.fieldThree)}
        errorMessage='Please enter digits only'
        className='mb2'>
          fieldThree (only digits)
      </Field>
      <Button type='submit' className='mt2'>Submit</Button>
    </form>
)};

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

    this.fields = {
      fieldOne: {},
      fieldTwo: {
        required: false
      },
      fieldThree: {
        validator: ({ value }) => {
          return { error: value === '' || /\D/.test(value) }
        }
      }
    };

    this.handleSubmit = this.handleSubmit.bind(this);
    this.handleError = this.handleError.bind(this);
  }

  handleSubmit(formData) {
    // All fields are valid, do something with the formData.
    // console.log('handleSubmit', formData);
  }

  handleError(invalidFields) {
    // Some fields are not valid.
    //console.log('handleError', invalidFields);
  }

  render() {
    return (
      <FormContainer
        focusOnSubmitError
        fields={ this.fields }
        onSubmit={ this.handleSubmit }
        onError={ this.handleError }
      >
        <ExampleForm />
      </FormContainer>
    );
  }
}

render(<FormContainerExample />);

const ExampleForm = ({ fields, isValid, onSubmit }) => {
  /**
   *
   * Example of a field state object:
   * {
   *   error: true, // true when previously valid or the input is blurred
   *   wasBlurred: true,
   *   wasChanged: true,
   *   wasValid: true,
   *   input: {
   *     id: "fieldOne",
   *     name: "fieldOne",
   *     onBlur: handleBlur,
   *     onChange: handleChange,
   *     required: true,
   *     value: ""
   *   }
   * }
  */
  // console.log('fieldState objects:', fields);
  // console.log('fields are valid', isValid);

  return (
    <form onSubmit={ onSubmit } noValidate>
      <Field
        { ...fields.fieldOne.input }
        error={ shouldDisplayError(fields.fieldOne)}
        errorMessage='Please enter a value'
        className='mb2'>
          fieldOne (required)
      </Field>
      <Field
        { ...fields.fieldTwo.input }
        className='mb2'>
          fieldTwo (optional)
      </Field>
      <Field
        { ...fields.fieldThree.input }
        error={ shouldDisplayError(fields.fieldThree)}
        errorMessage='Please enter digits only'
        className='mb2'>
          fieldThree (only digits)
      </Field>
      <Button type='submit' className='mt2'>Submit</Button>
    </form>
)};

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

    this.fields = {
      fieldOne: {},
      fieldTwo: {
        required: false
      },
      fieldThree: {
        validator: ({ value }) => {
          return { error: value === '' || /\D/.test(value) }
        }
      }
    };

    this.handleSubmit = this.handleSubmit.bind(this);
    this.handleError = this.handleError.bind(this);
  }

  handleSubmit(formData) {
    // All fields are valid, do something with the formData.
    // console.log('handleSubmit', formData);
  }

  handleError(invalidFields) {
    // Some fields are not valid.
    //console.log('handleError', invalidFields);
  }

  render() {
    return (
      <FormContainer
        focusOnSubmitError
        fields={ this.fields }
        onSubmit={ this.handleSubmit }
        onError={ this.handleError }
      >
        <ExampleForm />
      </FormContainer>
    );
  }
}

render(<FormContainerExample />);

EditField

Notes

EditField supports a callback that allows a consumer to provide any custom mechanism for populating a list of values in a field-like element. It is not a text-editable field component, but appears visually similar to one.

Props

buttonLabelany['Edit']
Text or element used as the label for the EditField button. Defaults to 'Edit'. This value should be screen reader friendly, so it may make sense to use the hiddenVisually class to provide extra context on the button. For example:
```
buttonLabel={ (
 <span>
   Edit <span className='hiddenVisually'>milk options</span>
 </span>
) }
```
childrennode*
Text or element passed to a child component to form a "label" that is actually just a span
containerPropsobject[{}]
Props applied to the field's outer container.
idstring
listPropsobject[{}]
Props applied to the list element.
onClickfunc*
A custom function that will update or populate the listed values. Clicks are handled by the wrapper div, so that the user may click anywhere in the field (not just on the button).
listItemsarray
An array of elements or strings rendered inside html list item elements. When present, the FloatLabel will shift into its active position.

<div  className="bg-white p3">
  <div style={{width:"343px"}}>
    <p className='pb3'><em>With no list items:</em></p>
    <EditField
      containerProps={ { className: 'mb9' } }
      listProps={ { 'data-e2e': 'myTest' } }
      id="no_list_items"
      onClick={ () => { alert('Button Clicked!') } }
    >
      Fill me in
    </EditField>

    <p className='pb3'><em>With list items:</em></p>
    <EditField
      listItems={ ['No foam', '2%', 'Truncate this really long name for me please'] }
      listProps={ { id: 'foo' } }
      id="with_list_items"
      onClick={ () => { alert('Hey stop it!') } }
    >
      Milk
    </EditField>
  </div>
</div>

<div  className="bg-white p3">
  <div style={{width:"343px"}}>
    <p className='pb3'><em>With no list items:</em></p>
    <EditField
      containerProps={ { className: 'mb9' } }
      listProps={ { 'data-e2e': 'myTest' } }
      id="no_list_items"
      onClick={ () => { alert('Button Clicked!') } }
    >
      Fill me in
    </EditField>

    <p className='pb3'><em>With list items:</em></p>
    <EditField
      listItems={ ['No foam', '2%', 'Truncate this really long name for me please'] }
      listProps={ { id: 'foo' } }
      id="with_list_items"
      onClick={ () => { alert('Hey stop it!') } }
    >
      Milk
    </EditField>
  </div>
</div>

Select

Notes

A select component that leverages the browser's built in select, layering on a styled label and presentation for the currently selected option.

Props

childrennode*
option elements associated with the select element.
classNamestring
customFieldStatusbool
A flag indicating that the field uses a custom element to display field status and should not wrap error messages in a FieldStatus component.
displayStatusbool
A flag indicating that the field should display its error message irrespective of the field's error status. If set to true, the error message will display no matter what. If set to false, it will never display.
errorbool
A flag indicating that the field is in an error state.
errorMessagenode
A message to display when the field is in an error state. Wrapped in a FieldStatus component by default.
idstring
labelstring*
namestring
onChangefunc
valuestring
selectedOptionFormatterfunc
A function allowing the select component's getSelectedOption to pass a custom text for the selected option. Returns custom text.

<div>
  <Select
    error={ false }
    errorMessage='Please select a day.'
    id='day'
    label='Day'
  >
    <option></option>
    <option>Monday</option>
    <option>Tuesday</option>
    <option>Wednesday</option>
    <option>Thursday</option>
    <option>Friday</option>
    <option>Saturday</option>
    <option>Sunday</option>
  </Select>

  <Select
    className='mt3'
    error={ true }
    errorMessage='Please select a month other than March.'
    id='month'
    label='Month'
    value='March'
    onChange={ ev => console.log(ev.target.value) }
  >
    <option>January</option>
    <option>February</option>
    <option>March</option>
    <option>April</option>
    <option>May</option>
    <option>June</option>
    <option>July</option>
    <option>August</option>
    <option>September</option>
    <option>October</option>
    <option>November</option>
    <option>December</option>
  </Select>
</div>

<div>
  <Select
    error={ false }
    errorMessage='Please select a day.'
    id='day'
    label='Day'
  >
    <option></option>
    <option>Monday</option>
    <option>Tuesday</option>
    <option>Wednesday</option>
    <option>Thursday</option>
    <option>Friday</option>
    <option>Saturday</option>
    <option>Sunday</option>
  </Select>

  <Select
    className='mt3'
    error={ true }
    errorMessage='Please select a month other than March.'
    id='month'
    label='Month'
    value='March'
    onChange={ ev => console.log(ev.target.value) }
  >
    <option>January</option>
    <option>February</option>
    <option>March</option>
    <option>April</option>
    <option>May</option>
    <option>June</option>
    <option>July</option>
    <option>August</option>
    <option>September</option>
    <option>October</option>
    <option>November</option>
    <option>December</option>
  </Select>
</div>

Checkbox

Notes

Props

errorbool
A flag indicating that the checkbox is in an error state.
errorMessagenode
A message to display when the checkbox is in an error state. Wrapped in a FieldStatus component by default.

<Checkbox>
  Remember me
</Checkbox>

<Checkbox>
  Remember me
</Checkbox>

Radio

Notes

Props

errorbool
A flag indicating that the radio input is in an error state.
errorMessagenode
A message to display when the radio input is in an error state. Wrapped in a FieldStatus component by default.

<Radio>
  I’d like an instant Digital Card.
</Radio>

<Radio>
  I’d like an instant Digital Card.
</Radio>

RadioGroup

Notes

An optional wrapper for groups of radio inputs. Passes name, required, onChange handler, and current checked status based on the value prop to any child radio inputs.

Props

childrennode
Components to be wrapped. Radio components and input elements with type="radio" have name, onChange, checked, and required passed to them. Other elements are passed through as-is.
namestring
onChangefunc
requiredbool
valuestring
The value of the currently selected radio button. A convenient way to handle controlled radio inputs. If the value property of the radio input matches the passed in value, that input will be checked.
legendstring*
Required description of radio buttons. Helpful for accessibility.

<RadioGroup name='rewardCards' legend='card options'>
  <Radio value='digitalCard'>
    I’d like an instant Digital Card.
  </Radio>

  <Radio value='registerCard'>
    I have a Starbucks Gift Card I’d like to register.
  </Radio>

  <Radio value='noCard'>
    I don’t want a Starbucks Card or Rewards.
  </Radio>
</RadioGroup>

<RadioGroup name='rewardCards' legend='card options'>
  <Radio value='digitalCard'>
    I’d like an instant Digital Card.
  </Radio>

  <Radio value='registerCard'>
    I have a Starbucks Gift Card I’d like to register.
  </Radio>

  <Radio value='noCard'>
    I don’t want a Starbucks Card or Rewards.
  </Radio>
</RadioGroup>

SegmentedControl

Notes

A pre-styled control that allows for multiple values in a tabbable-fashion (one selected at a time)

Props

visualStyleoneOf('default', 'dark', 'inverted')['default']
Controls the visual style of the component
inputs
arrayOf [
shape {
displayNamestring*
The displayed text of the input

valuestring*
The value of the input

iconPathstring
The path of the icon to be used

}
]
*
The inputs fields passed to the SegmentedControl. The number of inputs (objects) in the array determines the number of options shown within the SegmentedControl component.
onValueChangefunc*
A function called when the selected value of the the SegmentedControl changes (when an individual control is clicked). This function receives the value defined in the inputs prop
selectedValuestring
The currently selected value--the selected value will be highlighted
classNamestring
The classes applied to the container component

class SegmentedControlExample extends React.Component {
    constructor() {
        super();
        this.state = { selectedValue: 'drink' };
        this.handleChangeValue = this.handleChangeValue.bind(this);
    };

    handleChangeValue(value) {
        this.setState({ selectedValue: value });
    };

    render() {
        return (
            <SegmentedControl
                visualStyle="dark"
                inputs={[
                    {
                        displayName: 'Drink',
                        value: 'drink'
                    },
                    {
                        displayName: 'Food',
                        value: 'food'
                    },
                    {
                        displayName: 'Dessert',
                        value: 'dessert'
                    }
                ]}
                onValueChange={this.handleChangeValue}
                selectedValue={this.state.selectedValue}
            />
        );
    }
}

render(<SegmentedControlExample />);

class SegmentedControlExample extends React.Component {
    constructor() {
        super();
        this.state = { selectedValue: 'drink' };
        this.handleChangeValue = this.handleChangeValue.bind(this);
    };

    handleChangeValue(value) {
        this.setState({ selectedValue: value });
    };

    render() {
        return (
            <SegmentedControl
                visualStyle="dark"
                inputs={[
                    {
                        displayName: 'Drink',
                        value: 'drink'
                    },
                    {
                        displayName: 'Food',
                        value: 'food'
                    },
                    {
                        displayName: 'Dessert',
                        value: 'dessert'
                    }
                ]}
                onValueChange={this.handleChangeValue}
                selectedValue={this.state.selectedValue}
            />
        );
    }
}

render(<SegmentedControlExample />);

class SegmentedControlWithIconsExample extends React.Component {
    constructor() {
        super();
        this.state = { selectedValue: 'instore' };
        this.handleChangeValue = this.handleChangeValue.bind(this);
    };

    handleChangeValue(value) {
        this.setState({ selectedValue: value });
    };

    render() {
        return (
            <div className="bg-houseGreen p2">
                <SegmentedControl
                    visualStyle="inverted"
                    inputs={[
                        {
                            displayName: 'In store',
                            value: 'instore',
                            iconPath: iconPaths.pickupInStore
                        },
                        {
                            displayName: 'Drive-thru',
                            value: 'drivethru',
                            iconPath: iconPaths.pickupDriveThru
                        },
                        {
                            displayName: 'Curbside',
                            value: 'curbside',
                            iconPath: iconPaths.pickupCurbside
                        }
                    ]}
                    onValueChange={this.handleChangeValue}
                    selectedValue={this.state.selectedValue}
                />
            </div>
        );
    }
}

render(<SegmentedControlWithIconsExample />);

class SegmentedControlWithIconsExample extends React.Component {
    constructor() {
        super();
        this.state = { selectedValue: 'instore' };
        this.handleChangeValue = this.handleChangeValue.bind(this);
    };

    handleChangeValue(value) {
        this.setState({ selectedValue: value });
    };

    render() {
        return (
            <div className="bg-houseGreen p2">
                <SegmentedControl
                    visualStyle="inverted"
                    inputs={[
                        {
                            displayName: 'In store',
                            value: 'instore',
                            iconPath: iconPaths.pickupInStore
                        },
                        {
                            displayName: 'Drive-thru',
                            value: 'drivethru',
                            iconPath: iconPaths.pickupDriveThru
                        },
                        {
                            displayName: 'Curbside',
                            value: 'curbside',
                            iconPath: iconPaths.pickupCurbside
                        }
                    ]}
                    onValueChange={this.handleChangeValue}
                    selectedValue={this.state.selectedValue}
                />
            </div>
        );
    }
}

render(<SegmentedControlWithIconsExample />);

Toggle

Notes

A toggle for choice actions.

Props

classNamestring
typestring['checkbox']

<div>
  <label className='flex items-center justify-between'>
    <span>Auto reload</span>
    <Toggle />
  </label>
</div>

<div>
  <label className='flex items-center justify-between'>
    <span>Auto reload</span>
    <Toggle />
  </label>
</div>