@twintag/twintag-form

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:

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.