haunted-forms 👻

A lightweight form library for haunted-js

Installation

npm install @cpepin/haunted-forms

Examples below show components build with haunted and lit-html for templating.

IE11

This library requires the polyfills outlined in here, as well as a CustomEvent polyfill which you can find here.

Getting Started

In order to use the components exposed in this library, you will first need to register them using the register function.

// your entry point
import { register } from '@cpepin/haunted-forms';

/*
 * 'defines' the custom elements in the DOM
 */
register();

Components

hf-form

hf-form creates a FormContext, which child form elements using usField will register with.

Usage

<hf-form>
  <!-- Form Elements -->
</hf-form>

Attributes

• dont-prevent-default: (boolean) will trigger typical form submission behavior (refresh page)
• on-submit: ((values) => void) function invoked with the values from the form
• on-value-change: ((values) => void) function invoked with the form values, when a value has changed
• api-ref: ({ current: any }) accepts a ref provided by useRef, gives access to form api

Form API

• setValue: ((field, value) => void) updates a given form value
• getValue: ((field) => value) retrieves a form value
• getError: ((field) => error) retrieves a form error
• setError: ((field, error) => void) updates a given field's form error
• validate: (() => void) manually triggers form validation
• getState: (() => formState) retrieves the current state of the form

Form State

{
  hasError: boolean,
  fields: [
    {
      [field]: { value, error },
    },
  ],
}

useField

Hook for creating form fields.

Usage

import { useField } from '@cpepin/haunted-forms';

const MyTextInput = ({
  field,
  initialValue = '',
  validate,
  validateOnBlur,
  validateOnChange,
  validateOnRender,
}) => {
  const { error, handleBlur, handleChange, render } = useField({
    field,
    initialValue,
    validate,
    validateOnBlur,
    validateOnChange,
    validateOnRender,
  });

  return render(html`
    <input
      id="my-input"
      type="text"
      value=${initialValue}
      @input=${handleChange}
      @blur=${handleBlur}
    ></input>
    <div>${error}</div>
  `);
};

Params

• field: (string, required) name of the field (must be unique)
• initialValue: (any, default="") initial value of the field
• onValueChange: ((value) => void, default=() => {}) invoked when value has changed
• validate: ((value) => undefined | string, default=() => undefined) validation function to be run against the input. Returns undefined if no error exists.
• validateOnBlur: (boolean, default=false) run field validation on blur
• validateOnChange: (boolean, default=false) run field validation on change
• validateOnRender: (boolean, default=false) run field validation on render

useSubmitDispatcher

Hook used to dispatch a customer submit event from a form button. This is necessary, as normal submit events can not bubble up outside of the shadowRoot.

Usage

import { useSubmitDispatcher } from '@cpepin/haunted-forms';

const MySubmitButton = () => {
  const { dispatch } = useSubmitDispatcher();

  const handleClick = e => dispatch(e);

  return html`
    <button @click=${handleClick}>Submit</button>
  `;
};