@financial-times/o3-form

v0.4.0

Published

6 days ago

Provides a viewport-aware tooltip for annotating or or highlighting other aspects of a product's UI

Downloads

164

0High
0Medium
0Low

form input field fieldset submit file upload

o3-form

Provides components to construct forms.

Overview

o3-form provides UI form elements with consistent labelling, descriptions, and error styles and interfaces.

Components

Form

Form is the top-level component that wraps all form elements. It can be used as plain HTML:

<form class="o3-form">
 <!-- form elements go here -->
</form>

Or users can also import JSX components:

import {Form} from '@financial-times/o3-form/cjs'; // or esm

<Form>
 <!-- form elements go here -->
</Form>;

| Prop | Description | required | Type | Default | | ---------- | -------------------------------- | -------- | ---- | ------- | | children | The form elements to be rendered | true | any | - |

Form Field, Form Fieldset and Feedback

Form Field components can be complex and contain multiple elements. Form Field and Form Fieldset are containers for form elements. Shared anatomy of Form Field and Form Fieldset looks like composition of the following elements:

<form>
 <form-field-element>
  <title-label-element>
   Title/Label
  </title-label-element>
  <description-element>
   Description
  </description-element>
   <!-- form elements go here -->
  <feedback-element>
   Feedback
  </feedback-element>
 </form-field>
</form>

We are using Title and Label interchangeably. But we export two JSX components from o3-form package: TitledFormField and LabeledFormField. Both components are similar but TitledFormField is used with checkboxes, radio buttons and use-cases when <label> element needs to be part of form element or more flexibility is require. LabeledFormField is used with other text inputs.

The main difference between them is HTML they output. TitledFormField outputs:

<div className="o3-form-field">
 <span className="o3-form-field__title" id="{labelId}"> Title </span>
 <!--- Description -->
 {children}
 <!--- Feedback --->
</div>

And LabeledFormField outputs:

<div className="o3-form-field">
 <label className="o3-form-field__label" htmlFor="{id}"> label </label>
 <!--- Description -->
 {children}
 <!--- Feedback --->
</div>

TitleFormField expects children to contain both <input> and <label> elements, which helps us a lot with checkboxes and radio buttons. LabeledFormField expects children to contain only <input> element. Two components in JSX can be used as follows:

import {
 Form,
 TitledFormField,
 LabeledFormField,
 CheckBoxItem,
} from '@financial-times/o3-form/cjs'; // or esm

<Form>
 <TitledFormField label="Title for checkbox" description="Description">
  <input type="checkbox" id={inputId} />
  <label htmlFor={inputId}>Checkbox Label</label>
 </TitledFormField>

 <LabeledFormField
  label="Label for text input"
  description="Description"
  inputId={inputId}>
  <input type="text" id={inputId} />
 </LabeledFormField>
</Form>;

Form Field and Form Fieldset components have same props:

| Prop | Description | required | Type | Default | | ------------- | -------------------------------------------------------------------------------------------------- | -------- | ------ | ------- | | label | The label for the form fieldset | true | string | - | | inputId | The id of the form input element | false | string | - | | description | A description of the form fieldset | false | string | - | | children | The form elements to be rendered | true | any | - | | feedback | The feedback object for the form fieldset that contains message and type of message properties | false | string | - |

Form Fieldset is used to group related form elements together such as checkboxes. They can be used as plain HTML:

<form class="o3-form">
 <div class="o3-form-field">
  <fieldset className="o3-form-field" aria-describedby="descriptionId">
   <legend className="o3-form-field__legend ">
    Field group label/title
   </legend>
   <span className="o3-form-input__description" id="descriptionId">
    description of the field group
   </span>
   <!-- form elements go here -->
  </fieldset>
 </div>
</form>

Or users can also import JSX components:

import {Form, FormFieldset} from '@financial-times/o3-form/cjs'; // or esm

<Form>
 <FormFieldset label="Field group label/title" description="description of the field group">
 <!-- form elements go here -->
 </FormFieldset>
</Form>;

| Prop | Description | required | Type | Default | | ------------- | -------------------------------------------------------------------------------------------------- | -------- | ------ | ------- | | label | The label for the form fieldset | true | string | - | | description | A description of the form fieldset | false | string | - | | children | The form elements to be rendered | true | any | - | | feedback | The feedback object for the form fieldset that contains message and type of message properties | false | string | - |

Text Input

A standard text input for collecting text values. label: 'Full name', description: 'Your full name as printed on your driving license',

HTML

<div data-o3-brand="whitelabel">
  <div class="o3-form-field">
    <label for="my-input-field">Full name</label>
    <span
      class="o3-form-input-description"
    >
      Your full name as printed on your driving license
    </span>
    <input id="my-input-field" class="o3-form o3-form-text-input" type="text" />
  </div>
</div>

JSX

import {TextInput} from '@financial-times/o3-form/cjs'; // or esm

<TextInput
 label="Full name"
 disabled="{false}"
 description="Your full name as printed on your driving license"
/>

Short text input

The size and max length of the text input can be limited with the length property.

HTML

<div class="o3-form-field">
 <label for="my-input-field">Security Code</label>
 <span class="o3-form-input-description">
  3 digit security code as printed on the back of your credit card.
 </span>
 <input
  id="my-input-field"
  class="o3-form o3-form-text-input o3-form-text-input--short-3"
  maxlength="3"
  type="text"
 />
</div>

JSX

import {TextInput} from '@financial-times/o3-form/cjs'; // or esm

<TextInput
 label="Security code"
 description="3 digit security code as printed on the back of your credit card."
 length="{3}"
/>;

This will provide a text box 3 characters wide and only allow 3 characters to be typed.

If you prefer to limit the length without styling, use the maxLength attribute instead.

HTML

<div class="o3-form-field">
 <label for="my-input-field">Security Code</label>
 <span class="o3-form-input-description">
  3 digit security code as printed on the back of your credit card.
 </span>
 <input
  id="my-input-field"
  class="o3-form o3-form-text-input"
  maxlength="3"
  type="text"
 />
</div>

JSX

import {TextInput} from '@financial-times/o3-form/cjs'; // or esm

<TextInput
 label="Security code"
 description="3 digit security code as printed on the back of your credit card."
 feedback={args.feedback}
 attributes={{
  maxLength: 3,
 }}
/>

Checkbox

A customizable and accessible checkbox input for selecting one or more items from a list, or turning an item on or off. Checkbox can also have a state of indeterminate and o3-form provides styling, for indeterminate state but this state can only be set using javaScript. Read more about indeterminate state.

Checkboxes can be used as plain HTML:

<form class="o3-form">
 <div class="o3-form-field">
  <span class="o3-form-field__title" id="o3-form-label_Demo_ID">
   Check this box
  </span>
  <span class="o3-form-input__description" id="o3-form-description_DEMO_ID">
   Please check the box to continue
  </span>
  <div class="o3-form-input__checkbox">
   <input
    type="checkbox"
    id="checkbox_1"
    class="o3-form-input__checkbox-input o3-visually-hidden"
    required=""
    aria-required="true"
   />
   <label for="checkbox_1" class="o3-form-input__checkbox-label">
    I agree to the terms and conditions
   </label>
  </div>
 </div>
</form>

Or users can also import JSX components:

import {CheckBox, TitledFormField} from '@financial-times/o3-form/cjs'; // or esm

<TitledFormField>
 <CheckBox
  inputId="terms"
  checkboxLabel="I agree to the terms and conditions"
  optional={false}
 />
 ;
</TitledFormField>;

| Prop | Description | required | Type | Default | | --------------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ------- | | inputId | The id of the checkbox input | true | string | - | | checkboxLabel | The label for the checkbox | true | string | - | | feedback | The feedback object for the checkbox that contains message and type of message properties | false | string | - | | optional | Whether the checkbox is optional | false | boolean | - | | label | The title for the checkbox | false | string | - | | description | A description of the checkbox | false | string | - |

Checkbox Group

For multiple related checkboxes, use the CheckBoxGroup component:

<form class="o3-form">
 <fieldset
  class="o3-form-field"
  aria-describedby="o3-form-Interest-description"
 >
  <legend class="o3-form-field__legend">Select your interests</legend>
  <span class="o3-form-input__description" id="o3-form-Interest-description2">
   Choose all interests that apply
  </span>
  <div class="o3-form-input__checkbox">
   <input
    type="checkbox"
    id="interest-tech"
    class="o3-form-input__checkbox-input o3-visually-hidden"
   />
   <label for="interest-tech" class="o3-form-input__checkbox-label">
    Technology
   </label>
  </div>
  <div class="o3-form-input__checkbox">
   <input
    type="checkbox"
    id="interest-finance"
    class="o3-form-input__checkbox-input o3-visually-hidden"
   />
   <label for="interest-finance" class="o3-form-input__checkbox-label">
    Finance
   </label>
  </div>
  <div class="o3-form-input__checkbox">
   <input
    type="checkbox"
    id="interest-sports"
    class="o3-form-input__checkbox-input o3-visually-hidden"
   />
   <label for="interest-sports" class="o3-form-input__checkbox-label">
    Sports
   </label>
  </div>
 </fieldset>
</form>

import {CheckBoxGroup, CheckBoxItem} from '@financial-times/o3-form/cjs'; // or esm

<CheckBoxGroup
 label="Select your interests"
 description="Choose all that apply">
 <CheckBoxItem inputId="interest-tech" checkboxLabel="Technology" />
 <CheckBoxItem inputId="interest-finance" checkboxLabel="Finance" />
 <CheckBoxItem inputId="interest-sports" checkboxLabel="Sports" />
</CheckBoxGroup>;

| Attribute | Description | Type | Default | | ------------- | ---------------------------------------- | ---------- | ------- | | label | The label for the group of checkboxes | string | | | description | A description of the group of checkboxes | string | | | children | The checkboxes to be rendered | CheckBox[] | |

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

o3-form

Overview

Components

Form

Form Field, Form Fieldset and Feedback

Text Input

Short text input

Checkbox

Checkbox Group

Contact

Licence