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. |