@clubajax/react-form

React Form

Basic form elements for use in React.

The components are Dropdown, Popup, List, ActionMenu, Radios, Checkbox

Why React Forms?

There are many React libraries - unfortunately, because of the divide caused by CSS-in-JS, this cuts down on the libraies that will easily work in a project. Further factors, such as a code-bloated library, opinionated in style or icons

Install

yarn add @clubajax/react-form

npm install @clubajax/react-form

Demo

See React Form in action on clubajax.io

Accessibility

React Form aims to achieve ADA AA 2.0 - Americans with Disabilities Act, version 2.0, "Double A" compliance (not triple A)

Components have been tested for use without a mouse and with a screen reader.

TypeScript Safe

React Form comes with a tsconfig.json file for typings.

Style

React Form is styled with SCSS, so a stylesheet will need to be imported:

@import 'node_modules/@clubajax/react-form/lib/react-form.css';

React Form is very lightly styled, using grays and moderate padding and margins, so it will be easy to override to suit the application's needs.

Dropdown/ActionMenu Style

The Dropdown is an "inline" style, meaning that its popup is a descendant of the dropdown element tree, not an absolutely positioned DOMNode floating over the document. There are pros and cons to each style.

Inline Pros:

• Can be "stretchy" to the same size of the Dropdown button
• Can have custom positioning, left/right/center
• It is easy to inspect the DOM and debug
• It's easier to conditionally style the popup, since it is a descendant of the Dropdown and whatever className is used on it.
• Less complexity in the positioning, which leads to less code to maintain and relatively fewer bugs

Inline Cons:

• Certain page layouts cannot be used. Specifically anything with position: absolute (rare) or overflow: hidden (more common).
• The width of the popup is based on the component width, not the window width.

Absolute Positioned Pros and Cons are the inverse of the lists above.

Controlled vs Uncontrolled

You can choose whether to use the components as controlled or uncontrolled.

Controlled, which does not maintain its own state and expects the value to change via props, is the default. Use the value props as usual.

For uncontrolled, use defaultValue. This will maintain state internally. If you do not want to set an initial value but still wish to use it uncontrolled, pass: defaultValue={null}.

Usage

import { Dropdown } from '@clubajax/react-form';

const options = [
    {
        value: 'a',
        label: 'H Form 1'
    }, {
        value: 'b',
        label: 'H Form 2'
    }, {
        value: 'c',
        label: 'H Form 3'
    }
];

<Dropdown options={options} value="a" placeholder="Choose your kata..." label="Forms" />

Properties

Checkbox

• value [boolean, optional]: (Controlled) If provided, sets the value of the Checkbox, true checks the Checkbox
• defaultValue [boolean, optional]: (Uncontrolled) If provided, sets the value of the Checkbox, true checks the Checkbox
• label [string, optional]: If provided, creates a label element above the Dropdown
• checkAfter [boolean, optional]: If true, the check will be rendered after the label
• name [string, optional]: The name of the component (as used in forms). Will change the event (see below)
• onChange [function, optional]: The callback event when an item is selected (see Events below)

Radios

• options [array, required]: The items that will be used to create the radio buttons
  • value [string|integer, required]: The unique identifier of the option
  • label [string|DomNode, required]: The text that will display next to the radio button
  • class [string, optional]: A className that will be appended to that radio button
  • disabled [boolean, optional]: Will make that radio button non-selectable
• value [boolean, optional]: (Controlled) If provided, selects the radio with the matching value
• defaultValue [boolean, optional]: (Uncontrolled) If provided, selects the radio with teh matching value
• label [string, optional]: If provided, creates a label element above the radio buttons
• checkAfter [boolean, optional]: If true, the radio buttons will be rendered after the label
• name [string, optional]: The name of the component (as used in forms). Will change the event (see below)
• onChange [function, optional]: The callback event when an item is selected (see Events below)

Dropdown

• options [array, required]: The items that will be used to create the drop-down list
  • value [string|integer, required]: The unique identifier of the option
  • label [string|DomNode, required]: The text that will display in the drop-down list
  • class [string, optional]: A className that will be appended to the option in the drop-down list
  • alias [string, optional]: The alternative text that will display in the in the button, not the drop-down list
  • disabled [boolean, optional]: Will make that option non-selectable
• value [string|integer, optional]: (Controlled) If provided, sets the value of the Dropdown, and the display to the label of the option of that value
• defaultValue [string|integer, optional]: (Uncontrolled) If provided, sets the value of the Dropdown, and the display to the label of the option of that value
• label [string, optional]: If provided, creates a label element above the Dropdown
• name [string, optional]: The name of the component (as used in forms). Will change the event (see below)
• placeholder [string, optional]: The button display if no item is selected (defaults to "Select one...")
• onChange [function, optional]: The callback event when an item is selected (see Events below)

ActionMenu

ActionMenu is a button that opens a drop-down list. When an item is selected in the menu, an onAction event is called. The onAction event will fire, passing teh value from the list item.

• options [array, required]: The items that will be used to create the menu
  • value [string|integer, required]: The unique identifier of the option
  • label [string|DomNode, required]: The text that will display in the menu
  • class [string, optional]: A className that will be appended to the option in the menu
  • disabled [boolean, optional]: Will make that option non-selectable
• label [string, optional]: If provided, creates a label element above the Dropdown
• children [string | ReactNode, optional] Alternative to label: <ActionMenu>Label Here</ActionMenu>
• onAction [function, optional]: The callback event when an item is selected (see Events below)

Popup

The Popup will show/hide its contents, positioning itself relative to its parent/owner component. It will display whatever children are created in the JSX markup.

• buttonId [string|integer, required]: Popup will listen to the click event or Enter key of this DomNode ID.
• onOpen [function, optional]: The callback event when the Popup opens.
• onClose [function, optional]: The callback event when the Popup closes.
• isMenu [boolean, optional]: Causes a slightly different behavior, closing the popup more slowly so the selected item can be seen.

List

The List is a sub-component of the Dropdown, so it will look and work in a similar fashion.

• options [array, required]: The items that will be used to create the list
  • value [string|integer, required]: The unique identifier of the option
  • label [string|DomNode, required]: The text that will display in the list
  • class [string, optional]: A className that will be appended to the option in the list
  • disabled [boolean, optional]: Will make that option non-selectable
• value [string|integer, optional]: (Controlled) If provided, sets the value of the List, and the display to the label of the option of that value
• defaultValue [string|integer, optional]: (Uncontrolled) If provided, sets the value of the List, and the display to the label of the option of that value
• onChange [function, optional]: The callback event when an item is selected. It will pass the options item.
• isMenu [boolean, optional]: Will clear selection on close.

Events for Dropdown, Radios, and Checkbox

If the name prop is not used, the onChange event simply passes the value.

If the name prop is used, the event has the following shape, for maximum versatility:

{
    value: value,
    name: props.name
    [props.name]: value,
    target: <DomNode> {
        ...
        value: value,
        name: props.name
    }
}

License

Free as in beer.