Neil Patrick's Mansion

    @clubajax/react-form
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.1 • Public • Published

    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.

    Keywords

    none

    Install

    npm i @clubajax/react-form

    DownloadsWeekly Downloads

    1

    Version

    0.6.1

    License

    MIT

    Unpacked Size

    72.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • mwilcox