@twintag/twintag-form

1.5.0 • Public • Published

Twintag Form

Content

Introduction

Twintag Form provides a web component that allows you to create a form based on a JSON object, leaving the actions to the developer.

Framework Agnostic

Twintag Form exposes a web component that can be used in any framework or vanilla JS.

<twintag-form options="..." config="[...]"></twintag-form>

Parameters

The form component receives the following parameters:

Parameter Type Description
config array Array that contains the form structure.
options object Options to customize the form

Config

The config object contains the form structure. It is organized by the index of the items, where each item is an Input field represented by an object with the following properties:

Property Type Description
type string Component type. The subtype is optional as part of the string: input:<subtype>
subtype string Component subtype
label string Field label.
bind string Field name.
[
  {
    "type": "input",
    "props": {
      "subtype": "simple",
      "label": "Email",
      "bind": "email"
    }
  },
  {
    "type": "input:textarea",
    "props": {
      "label": "Message",
      "bind": "message"
    }
  },
  {
    "type": "input",
    "props": {
      "subtype": "submit",
      "label": "Submit"
    }
  }
]

Options

Twintag Form provides some options to customize the form:

Option Type Description
variant default / beta Variant of the form.
size base / sm Default: base (font-size set to 16px).
resetOnSubmit boolean If true, the form will be reset after submitting. (false per default)
defaultValues object The properties are the same as the bind values in your config.

Inputs

Input options

Each input can be customized with the following optional options:

Option Type Description
description string Description of the input.
error string Error message.
placeholder string Placeholder of the input.
optionalField boolean If true, the field will be optional. (false per default)
{
  "type": "input",
  "props": {
    "subtype": "simple",
    "label": "Email",
    "bind": "email",
    "options": {
      "description": "Please enter you email",
      "error": "The field is empty."
      "placeholder": "Write here...",
      "optionalField": true
    }
  }
}

Subtypes

  • Simple
{
  "type": "input",
  "props": {
    "subtype": "simple",
    "label": "Email",
    "bind": "email"
  }
}
  • Textarea
{
  "type": "input",
  "props": {
    "subtype": "textarea",
    "label": "Message",
    "bind": "message"
  }
}
  • File
{
  "type": "input",
  "props": {
    "subtype": "file",
    "label": "File",
    "bind": "file"
  }
}
  • Checkbox
{
  "type": "input",
  "props": {
    "subtype": "checkbox",
    "label": "Checkbox",
    "bind": "checkbox"
  }
}
  • Toggle
{
  "type": "input",
  "props": {
    "subtype": "toggle",
    "label": "Toggle",
    "bind": "toggle"
  }
}
  • Tri-Toggle
{
  "type": "input",
  "props": {
    "subtype": "tri-toggle",
    "label": "Toggle with 3 states",
    "bind": "tri-states"
  }
}
  • Radiogroup
{
  "type": "input",
  "props": {
    "subtype": "radiogroup",
    "label": "Radio Group",
    "bind": "radiogroup",
  },
  "children": [
    {
      "type": "item",
      "props": {
        "label": "First item",
        "bind": "first-item"
      }
    },
    ...
  ]
}
  • Submit
{
  "type": "input",
  "props": {
    "subtype": "submit",
    "label": "Submit"
  }
}
  • Date picker
{
  "type": "input",
  "props": {
    "subtype": "datepicker",
    "label": "Pick a date"
  }
}

Containers

  • Accordion
{
  "type": "accordion",
  "props": {
    "defaultValue": "first-item" // optional: default expanded item
  },
  "children": [
    {
      "type": "accordion",
      "props": {
        "subtype": "item",
        "value": "first-item", // optional
        "label": "Your label",
        "icon": "archive-box-x-mark"
      },
      "children": [
        {
          "type": "input",
          "props": {
            "subtype": "simple",
            "bind": "first-item"
          }
        },
      ...
      ]
    },
    ...
  ]
}
  • Category
{
  "type": "category",
  "props": {
    "label": "Category"
  },
  "children": [
    {
      "type": "input",
      "props": {
        "subtype": "simple",
        "label": "Your label"
      }
    },
    ...
  ]
}

Event Handling

<twintag-form
  id="yourform"
  options='{"variant":"beta","resetOnSubmit":true}'
  config='[{"type":"input:toggle","label":"Test","bind":"test","options":{"optionalField":true}},{"type":"input:submit","label":"Submit"}]'
></twintag-form>

<button id="submit-btn">Submit</button>
<button id="get-values-btn">Submit</button>

<script>
  const form = document.getElementById('yourform');
  const submit = document.getElementById('submit-btn');
  const getValues = document.getElementById('get-values-btn');

  // You can validate the form outside the component:
  submit.addEventListener('click', () => {
    const submitEvent = new Event('twintag-form-validate');
    form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
  });

  // If there are no errors, the form will emit a custom event with the data on submit
  form.addEventListener('twintag-form-valid', (e) => {
    console.log(e.detail); // { test: true }
  });

  // If there are errors, the form will emit a custom event with the errors
  form.addEventListener('twintag-form-invalid', (e) => {
    console.log(e.detail); // { test: 'Test is required' }
  });

  // You can get the values of the form outside the component:
  form.addEventListener('twintag-form-values', (e) => {
    console.log(e.detail);
  });
  getValues.addEventListener('click', () => {
    const getValuesEvent = new Event('twintag-form-get_values');
    form.shadowRoot.querySelector('form').dispatchEvent(getValuesEvent);
  });
</script>

CSS

The form component exposes the following CSS variables:

Variable Description
--tf-label Color used for the inputs label.
--tf-category Color used for the category labels.
--tf-background Background color for the input fields.
--tf-foreground Text color for the input fields.
--tf-muted Used for toggle and tri-toggle background when value is false.
--tf-muted-foreground Color used for placeholder text (inputs) and description text.
--tf-primary This color complements primary-foreground: submit button text
--tf-primary-foreground This color is used for, submit background, label text and input value.
--tf-accent The accent color is used for toggle, tri-toggle, checkbox and radiogroup inputs.
--tf-accent-foreground This color complements accent to show contrast between elements: checkbox check icon.
--tf-destructive This color is used for error messages and the asterisk to mark a required input.
--tf-input This color is used by the input borders.
--tf-ring This color highlights a focused input.
--tf-radius This value is used for input rounded corners.
--tf-font Font family for all the form.

Readme

Keywords

none

Package Sidebar

Install

npm i @twintag/twintag-form

Weekly Downloads

0

Version

1.5.0

License

none

Unpacked Size

1.52 MB

Total Files

90

Last publish

Collaborators

  • twintag-ci