@halo-lab/svelte-form-getform-io

This is a Svelte form component library, intended to be used with Getform and svelte-forms. It provides a number of components (such as inputs, checkboxes, etc.) that intergrate with svelte-forms fields, a wrapper Form component that integrates with Getform, as well as helpful custom validators for svelte-forms.

Requirements

• Svelte project ready to go
• Getform API key

Installation

npm install svelte-forms @halo-lab/svelte-form-getform-io

Usage

Setting up svelte-forms

To create your form, you would first need to create all your svelte-forms fields. Our package provides 5 basic types of fields:

• TextField - a regular text input or a textarea
• CheckboxField - a checkbox
• RadioGroupField - a radio button group
• SelectField - a selection box with a search bar
• FileField - a file input

Here is how to initialize all of these types in svelete-forms:

<script>
  import type { TextField, CheckboxField, RadioGroupField, SelectField, FileField } from "@halo-lab/svelte-form-getform-io";
  import { form, field } from 'svelte-forms';

  const fieldName = field<TextField>('name', ''); // accepts a string as the initial value
  const fieldTerms = field<CheckboxField>('terms', false); // accepts a boolean as the initial value
  const fieldRadio = field<RadioGroupField>('radio', ''); // accepts a string (id of the selected option or empty) as the initial value
  const fieldCategory = field<SelectField>('category', ''); // accepts a string (id of the selected option or empty) as the initial value
  const fieldImages = field<FileField>('images', undefined); // accepts undefined as the initial value

  const myForm = form(
    fieldName, fieldTerms, fieldRadio, fieldCategory, fieldImages
  );
</script>

Notice that all of the fields are put into a single form function. This is a requirement of svelte-forms.

Setting up the form

After you have created your fields, you can now create a form. To do this, you would need to import the Form component from our package and pass it your Getform API key and optionally the onFormSubmit callback function.

Inside the Form component, you can now pass all of your fields as props to the corresponding components. All of the components accept a title prop, which is the label of the field, a field prop, which binds the field to the component, as well as other props, which are specific to the component.

<script>
  // add this to your imports
  import { Form, FormText, FormCheckbox, FormRadioGroup, FormSelect, FormFile } from "@halo-lab/svelte-form-getform-io";
</script>

<Form 
  getformId="your-getform-id"
  onFormSubmit={(data) => console.log(data.name, data.terms, data.category)}
>
  <FormText 
    title="Your Name" 
    type="text" 
    bind:field={$fieldName}
  />
  <FormCheckbox
    title="I agree to the Terms of Service"
    bind:field={$fieldTerms}
  />
  <FormRadioGroup
    title="Radio"
    groupId="radio"
    options={[
        { id: 'first', label: 'First' },
        { id: 'second', label: 'Second' },
        { id: 'third', label: 'Third' }
    ]}
    bind:field={$fieldRadio}
  />
  <FormSelect
    title="Category"
    options={[
        { id: 'suggestions', label: 'Suggestions' },
        { id: 'bugs', label: 'Bugs' },
        { id: 'other', label: 'Other' },
    ]}
    bind:field={$fieldCategory}
  />
  <FormFile
    title="Images"
    accept="image/*"
    multiple
    description="Supported formates: JPEG, PNG, GIF, WEBP"
    bind:field={$fieldImages}
  />
</Form>

Validation

Usually, you would want to validate your form before submitting it. To do this, svelte-forms package provides a number of validators. Validators are functions that can be provided to the field as an array. Here's an example:

const fieldName = field<TextField>('name', '', [required(), max(32)]); // must not be empty and must not be shorter than 32 characters

Our package also provides a number of custom validators, which are:

• checked - for validating checkboxes
• fileRequired - for validating file inputs

// add this to your imports
import { checked, fileRequired } from "@halo-lab/svelte-form-getform-io/validators";

const fieldTerms = field<CheckboxField>('terms', false, [checked()]); // must be checked
const fieldImages = field<FileField>('images', undefined, [fileRequired()]); // must have at least one file attached

Additionally, you can create your own custom validators. More information on this can be found on the official svelte-forms docs.

Custom Error Messages

By default, when a UI component fails validation, it will display a generic error message. You can override the error message for each validator individually by passing it an object to the errorText prop of the component. Here's an example:

<FormText 
  title="Your Name" 
  type="text" 
  bind:field={$fieldName}
  errorText={{
    required: 'This field is required', // this message will be displayed if the field is empty
    max: 'This field must not be longer than 32 characters' // this message will be displayed if the name is too long
    default: 'This field is invalid' // fallback message
  }}
/>

Documentation

Components

• Form

  The base form component. It acts as a holder for all of the other components, such as inputs and checkboxes.

  | Prop | Type | Description | | --- | --- | --- | | getformId | string | Getform API key | | onFormSubmit | (data: FormSubmitData) => void = () | Callback function to handle form submit | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

• FormText

  A text input component. You can use this components for simple inputs, emails or long messages.

  | Prop | Type | Description | | --- | --- | --- | | title | string | Input title | | type | 'text' | 'email' | 'message' = 'text' | Input type. Defaults to text | | field | Field<TextField> | svelte-forms field to bind the input to | | errorText | { [key: string]: string } = {} | Custom error messages for validators | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

• FormCheckbox

  A checkbox component.

  | Prop | Type | Description | | --- | --- | --- | | title | string | Checkbox label | | field | Field<CheckboxField> | svelte-forms field to bind the checkbox to | | errorText | { [key: string]: string } = {} | Custom error messages for validators | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

• FormRadioGroup

  A radio group components. You can use this component to let the user choose an option out of a few.

  | Prop | Type | Description | | --- | --- | --- | | title | string | Radio group title | | groupId | string | Radio group ID. This should be unique for every component | | options | RadioGroupOption[] = [] | Radio group options. An option is an object that contains id and label fields. Option ids must be unique relative to the component | | field | Field<RadioGroupField> | svelte-forms field to bind the radio group to | | errorText | { [key: string]: string } = {} | Custom error messages for validators | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

• FormSelect

  A selection box with a search bar. You can use this component to let the user choose an option out of a large list.

  | Prop | Type | Description | | --- | --- | --- | | title | string | Select title | | options | SelectOption[] = [] | Select options. An option is an object that contains id and label fields. Option ids must be unique relative to the component | | defaultText | string = 'Select an option' | Text to display when no option is selected | | field | Field<SelectField> | svelte-forms field to bind the select to | | errorText | { [key: string]: string } = {} | Custom error messages for validators | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

• FormFile

  A file input component with a dropzone and a list of selected files. It can be customized to accept multiple files and files of a specific type.

  | Prop | Type | Description | | --- | --- | --- | | title | string | File input title | | description | string | Text to display inside the dropzone. We recommend using this prop to specify the accepted file formats | | accept | string = '*' | File formats to accept. Defaults to all formats | | multiple | boolean = false | Whether to accept multiple files | | field | Field<FileField> | svelte-forms field to bind the file input to | | errorText | { [key: string]: string } = {} | Custom error messages for validators | | globalClass | string = '' | A custom class for the component. When styling, make sure to use the :global selector, as this is currently a limitation of how Svete scopes styles |

Field types

• TextField Data type for text inputs. It is a string.

• CheckboxField Data type for checkboxes. It is a boolean.

• RadioGroupField Data type for radio groups. It is a string.

• SelectField Data type for select boxes. It is a string.

• FileField Data type for file inputs. It can be undefined or an instance of an internal file list class.

Validators

These types should be imported from @halo-lab/svelte-form-getform-io/validators.

• checked This validator returns an error if the checkbox is not checked (another words, if the value is not true).

• fileRequired This validator returns an error if the file list is empty.

Other types

• FormSubmitData

  Data type for the onFormSubmit callback

  {
      name: string;
      email: string;
      message: string;
  }

• RadioGroupOption

  Data type for radio group options

  {
      id: string;
      label: string;
  }

• SelectOption

  Data type for select options

  {
      id: string;
      label: string;
  }

Word from the author

Have fun ✌️