Skip to content

Latest commit

 

History

History
424 lines (374 loc) · 9.93 KB

API.md

File metadata and controls

424 lines (374 loc) · 9.93 KB
Raw

API

All controls share the following properties:

  • model: a required string that will determine the name of your control, e.g. 
    model="username"
  • validator: an optional array of validator functions that will validate your input. Every validator must return a string when the validation fails e.g. 
    // multi line
const isRequired = val => {
  if (val && val.length > 0) {
    return;  // can also return false
  }
  return 'This field is required';
};
validator={[isRequired]}

// single line
validator={[val => (val && val.length > 0) || 'This field is required']}
    Since the validator prop accepts an array of validators, you can have multiple validators per control.
  • validateOn: an optional enum (blur, focus, input, mount) that detirmines at what point the validator starts to validate. Default is mount, e.g. 
    validateOn="blur"
  • className: optional for class style and compatible with CSS modules, e.g. 
    className={styles.button}
  • style: optional for inline style, e.g. 
    style={{color: 'red'}}
  • id: optional string to attach a label to the control, e.g. 
    id="age_1337"
  • disabled: optional boolean if the control should be disabled, e.g. 
    disabled={true}
  • onChange: an optional function that allows you to catch the on change event, e.g. 
    onChange={(model, value) => console.log(model, value)}

Button

import {Button} from 'react-chloroform';

Attributes

  • type: optional string descriping the button type, default button, e.g. 
    type="submit"
  • text: required string for the button text, e.g.
text="Submit form"
  • onClick: optional event handler function to catch when the button was clicked, e.g. 
    onClick={() => console.log('Button was clicked')}

Example

<Button
  type="submit"
  text="Submit"
  className={styles.submitButton}
/>

<Button
  type="reset"
  text="Reset"
/>

Checkbox

import {Checkbox} from 'react-chloroform';

Attributes

  • group: an optional string for when you want to group checkboxes together with the reserved all checkbox, e.g. 
    group="drinks"
    • validation: grouped checkboxes offer a validation. The validation must be set on the reserved all checkbox, e.g. 
      <label htmlFor="all_1">All</label>
<Checkbox
  model="all"
  id="all_1"
  group="drinks"
  validator={[isRequired]}
  validateOn="input"
/>

Example

<label htmlFor="cocacola_1">Coca Cola</label>
<Checkbox
  model="cocacola"
  id="cocacola_1"
  group="drinks"
/>

<label htmlFor="pepsi_1">Pepsi</label>
<Checkbox
  model="pepsi"
  id="pepsi_1"
  group="drinks"
/>

ChloroformError

import {ChloroformError} from 'react-chloroform';

This component renders the errors from your control validation.

Attributes

  • component: a required node/func that will render your errors, e.g. 
    component={({error}) => <p>{error}</p>}

Example

<FormInput
  model="name"
  validator={[isRequired]}
/>
<ChloroformError
  model="name"
  component={({error}) => <p className={styles.error}>{error}</p>}
/>

DataList

import {DataList} from 'react-chloroform';

Attributes

  • options: an array of options that will be rendered by the datalist. The option attributes are:
    • name: an optional string that further describes this option.
    • value: a required string or a number that determines the value of the option.
    • disabled: an optional boolean if this option should be disabled.
    options={[{name: 'Name', value: 'Value'}]}
  • placeholder: an optional placeholder for the input, e.g. 
    placeholder="Select gender"

Example

const options = [
  {
    name: 'React',
    value: 'react',
  },
  {
    name: 'Angular',
    value: 'angular',
    disabled: true,
  },
];

<DataList
  options={options}
  model="javascript"
  placeholder="What are you using for your front-end"
/>

FormInput

import {FormInput} from 'react-chloroform';

Attributes

  • placeholder: an optional placeholder for the input, e.g. 
    placeholder="Write something..."
  • type: your text input type, e.g. 
    type="password"

Example

<FormInput
  model="email"
  type="email"
  validator={[isEmail}]
/>

Form

import {Form} from 'react-chloroform';

This is the wrapper form needed to collect the user input.

Attributes

  • afterSubmitState: an optional object that allows you to re-initialise your state with prefilled values after submit, e.g. 
    afterSubmitState={{email: '', jobTitle: 'developer'}}
  • initialState: an optional object that allows you to initialise your state with prefilled values, e.g. 
    initialState={{email: '[email protected]', jobTitle: 'developer'}}
  • onReset: an optional function that allows you to catch the on reset event, e.g. 
    onReset={() => console.log('Form reset called')}
  • onResetState: an optional object that allows you reset your state to a predefined object. The default is the initialState, e.g. 
    onResetState={{}}
  • onSubmit: a required function that allows you to catch the on submit event, e.g. 
    onSubmit={model => console.log(model)}
  • onSubmitFailed: an optional function that allows you to catch if the form submit fails, e.g. 
    onSubmitFailed={error => console.log(error)}
  • onChange: an optional function that allows you to catch the on change event, e.g. 
    onChange={model => console.log(model)}

Example

const initialState = {
  name: 'Darri',
  age: 1337,
};

const handleSubmit = model => console.log(model);

<Form
  initialState={initialState}
  onSubmit={handleSubmit}
>
  ...
</Form>

RadioButton

import {RadioButton} from 'react-chloroform';

All radio buttons in the same group need to share the same model name.

Attributes

  • value: a required string/number representing the value of the radiobutton, e.g. 
    value="true"

Example

<label htmlFor="pepsi_2">Pepsi</label>
<RadioButton
  id="pepsi_2"
  model="drink"
  value="pepsi"
/>

<label htmlFor="cocacola_2">Coca Cola</label>
<RadioButton
  id="cocacola_2"
  model="drink"
  value="coca cola"
/>

Select

import {Select} from 'react-chloroform';

Attributes

  • options: an array of options that will be rendered by the select. The option attributes are:
    • name: a required string that further describes this option.
    • value: a required string or a number that determines the value of the option.
    • disabled: an optional boolean if this option should be disabled.
    options={[{name: 'Name', value: 'Value'}]}
    • The options can also be grouped together. The following are the attributes when grouping is needed:
      • name: a required string that further describes this group.
      • disabled: an optional boolean if this group should be disabled.
      • group: a required array of options.
      options={[{name: 'drinks', group: [{name: 'Pepsi', value: 'pepsi'}]}
  • placeholder: an optional placeholder for the select, e.g. 
    placeholder="Choose your option"

Example

const options = [
  {
    name: 'React',
    value: 'react',
  },
  {
    name: 'Other',
    disabled: true,
    group: [
      {
        name: 'Angular',
        value: 'angular',
      }
    ],
  },
];

<Select
  options={options}
  model="interests"
  placeholder="What do you love the most?"
/>

TextArea

import {TextArea} from 'react-chloroform';

Attributes

  • cols: an optional number specifying the width in avg character width, default 30, e.g. 
    cols={10}
  • rows: an optional number specifying the height in lines, default 10, e.g. 
    rows={5}
  • placeholder: an optional placeholder for the text area, e.g. 
    placeholder="Write here..."

Example

<TextArea
  model="details"
  placeholder="Write some details..."
  rows={300}
/>

withReactChloroform

import {withReactChloroform} from 'react-chloroform';

A HOC allowing you to write your own component with react-chloroform support and behaviour.

Attributes

  • chloroformStatus: a string representing the status of the form. The status is undefined when nothing is occurring. Otherwise it's one of:
    • submitted: when the form is submitting
    • submitting: if submission succeeded
    • failed: if submission failed
    • hasErrors: if the form has errors e.g.
    <button>{chloroformStatus === 'submitting' ? <Loading /> : 'Submit'}</button>
  • error: contains the errors from your validation, e.g. 
    {error && <p>{error}</p>}
  • value: a string/number that the HOC passes down as a prop, e.g. 
    value={value}
  • onChange: a function that the HOC passes down as a prop, e.g. 
    onChange={e => onChange(e.target.value)}
  • startValidating: you can optionally bind the startValidating function to an event handler. By default, the validation will be done on mount, e.g. 
    onBlur={startValidating}
  • showError: a boolean representing if your component should show the error. This depends on the startValidating property, e.g. 
    {showError && error && <p>{error}</p>}

Example

---
const MyInput = ({value, onChange, startValidating}) =>
  <div>
    <input
      value={value}
      onChange={e => onChange(e.target.value)}
      onFocus={startValidating}
    />
  </div>;
  
export default withReactChloroform(MyInput);
---

// then use your custom component
<MyInput
  model="custom"  // don't forget the required model
  validator={[isRequired]}
/>