@twintag/twintag-form v1.5.0

Twintag Form

Content

• Introduction
• Framework Agnostic
• Parameters
  • Config
  • Options
  • Inputs
    • Options
    • Subtypes
• Event Handling
• CSS

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:

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:

[
  {
    "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:

Inputs

Input options

Each input can be customized with the following optional options:

{
  "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: