@twintag/twintag-form NPM

Twintag Form

Content

Introduction
Framework Agnostic
Parameters
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:

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",
    "subtype": "simple",
    "label": "Email",
    "bind": "email"
  },
  {
    "type": "input:textarea",
    "label": "Message",
    "bind": "message"
  },
  {
    "type": "input",
    "subtype": "submit",
    "label": "Submit"
  }
]

Options

Twintag Form provides some options to customize the form:

Option	Type	Description
`variant`	`default/beta`	Variant of the form.
`resetOnSubmit`	`boolean`	If `true`, the form will be reset after submitting. (`false` per default)

Inputs

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",
  "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",
  "subtype": "simple",
  "label": "Email",
  "bind": "email"
}

Textarea

{
  "type": "input",
  "subtype": "textarea",
  "label": "Message",
  "bind": "message"
}

File

{
  "type": "input",
  "subtype": "file",
  "label": "File",
  "bind": "file"
}

Checkbox

{
  "type": "input",
  "subtype": "checkbox",
  "label": "Checkbox",
  "bind": "checkbox"
}

Toggle

{
  "type": "input",
  "subtype": "toggle",
  "label": "Toggle",
  "bind": "toggle"
}

Radiogroup

{
  "type": "input",
  "subtype": "radiogroup",
  "label": "Radio Group",
  "bind": "radiogroup",
  "children": [
    {
      "type": "item",
      "label": "First item",
      "bind": "first-item"
    },
    ...
  ]
}

Submit

{
  "type": "input",
  "subtype": "submit",
  "label": "Submit"
}

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="btn">Submit</button>

<script>
  const form = document.getElementById('yourform');
  const btn = document.getElementById('btn');

  // 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 validate the form outside the component:
  btn.addEventListener('click', () => {
    const submitEvent = new Event('twintag-form-validate');
    form.shadowRoot.querySelector('form').dispatchEvent(submitEvent);
  });
</script>

CSS

The form component exposes the following CSS variables:

Variable	Description
--tf-background	Background color for the input fields.
--tf-foreground	Color used for the `category` labels.

--tf-muted	Used for `switch` 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 `switch`, `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 borders of the inputs.
--tf-ring	This color highlights a focused input.

--tf-radius	This value is used for rounded corners of all inputs.

--tf-font	Font family for all the form.