Guide

Framework integrations

Use @samline/forms in React, Vue, Svelte, Astro, Shopify and WordPress by creating one controller after the form mounts and destroying it on unmount.

@samline/forms is a DOM controller, not a set of framework components. Every host follows the same ownership rule: create one controller when the <form> exists in the browser, keep the returned object, and call destroy() when that form goes away. There are no adapters to install.

JavaScript and TypeScript

Plain JavaScript needs nothing beyond the first form. TypeScript can import every option and callback type from the same package — FormController, FormControllerOptions, ValidationSchema, FormStateSnapshot and more. Check reusable rule sets with satisfies ValidationSchema; see the TypeScript reference.

React, Vue and Svelte

Let the framework render the form once and leave its fields uncontrolled: the controller reads values from the DOM. Render only what depends on state, such as messages and disabled buttons, from a subscribe() listener. Each component instance owns its own controller and ids.

React

Newsletter.jsx

Newsletter.jsx
import { useEffect, useId, useRef, useState } from 'react'
import { form } from '@samline/forms'

const validators = {
  email: {
    required: { value: true, message: 'Enter your email.' },
    pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Use a valid email.' },
  },
}

export function Newsletter() {
  const id = useId()
  const ref = useRef(null)
  const [state, setState] = useState({ errors: {}, isSubmitting: false })

  useEffect(() => {
    const controller = form(ref, { autoValidate: false, validators })
    const stop = controller.subscribe(setState)
    controller.onSubmit(async (_element, _data, formData) => {
      await fetch('/api/newsletter', { method: 'POST', body: formData })
      controller.reset()
    })
    return () => {
      stop()
      controller.destroy()
    }
  }, [])

  const error = state.errors.email?.[0]
  return (
    <form ref={ref} noValidate>
      <label htmlFor={id}>Email</label>
      <input id={id} name="email" type="email" aria-describedby={`${id}-error`} />
      <p id={`${id}-error`} aria-live="polite">
        {error}
      </p>
      <button type="submit" disabled={state.isSubmitting}>
        Subscribe
      </button>
    </form>
  )
}

Vue

Newsletter.vue

Newsletter.vue
<script setup>
import { onBeforeUnmount, onMounted, ref, useId } from 'vue'
import { form } from '@samline/forms'

const id = useId()
const element = ref(null)
const errors = ref({})
const isSubmitting = ref(false)
let controller

onMounted(() => {
  controller = form(element.value, {
    autoValidate: false,
    validators: {
      email: {
        required: { value: true, message: 'Enter your email.' },
        pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Use a valid email.' },
      },
    },
  })
  controller.subscribe(state => {
    errors.value = state.errors
    isSubmitting.value = state.isSubmitting
  })
  controller.onSubmit(async (_element, _data, formData) => {
    await fetch('/api/newsletter', { method: 'POST', body: formData })
    controller.reset()
  })
})

onBeforeUnmount(() => controller?.destroy())
</script>

<template>
  <form ref="element" novalidate>
    <label :for="id">Email</label>
    <input :id="id" name="email" type="email" :aria-describedby="`${id}-error`" />
    <p :id="`${id}-error`" aria-live="polite">{{ errors.email?.[0] }}</p>
    <button type="submit" :disabled="isSubmitting">Subscribe</button>
  </form>
</template>

Svelte

Newsletter.svelte

Newsletter.svelte
<script>
  import { onMount } from 'svelte'
  import { form } from '@samline/forms'

  const id = `newsletter-${Math.random().toString(36).slice(2)}`
  let element
  let errors = $state({})
  let isSubmitting = $state(false)

  onMount(() => {
    const controller = form(element, {
      autoValidate: false,
      validators: {
        email: {
          required: { value: true, message: 'Enter your email.' },
          pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Use a valid email.' },
        },
      },
    })
    controller.subscribe(state => {
      errors = state.errors
      isSubmitting = state.isSubmitting
    })
    controller.onSubmit(async (_element, _data, formData) => {
      await fetch('/api/newsletter', { method: 'POST', body: formData })
      controller.reset()
    })
    return () => controller.destroy()
  })
</script>

<form bind:this={element} novalidate>
  <label for={id}>Email</label>
  <input {id} name="email" type="email" aria-describedby="{id}-error" />
  <p id="{id}-error" aria-live="polite">{errors.email?.[0] ?? ''}</p>
  <button type="submit" disabled={isSubmitting}>Subscribe</button>
</form>
  • React creates the controller in useEffect and destroys it in the cleanup, which also handles the development double-mount of Strict Mode. If you need a controlled input, write changes through controller.setValue() so validation and watchers run.
  • Vue creates it in onMounted and destroys it in onBeforeUnmount.
  • Svelte 5 returns the cleanup from onMount.
  • In SSR frameworks, importing the package on the server is safe; creating a controller is not. Keep form() inside client lifecycle hooks.

These components were checked for syntax with Prettier’s Babel and Vue parsers; they were not compiled by React, Vue or Svelte toolchains in this repository. Lifecycle references: React Effects, Vue lifecycle hooks, Svelte onMount.

Astro

Create controllers in a processed client <script>, not in frontmatter. Astro bundles the import and runs it once per page.

<form id="signup" novalidate>
  <label for="email">Email</label>
  <input id="email" name="email" type="email" />
  <button type="submit">Sign up</button>
</form>

<script>
  import { form } from '@samline/forms'

  const signup = form('signup', { validators: { email: { required: true } } })
  window.addEventListener('pagehide', event => {
    if (!event.persisted) signup.destroy()
  })
</script>

With view transitions (<ClientRouter />), set up on astro:page-load and call destroy() on astro:before-swap, so each visit gets one controller and the previous page’s listeners are released.

Shopify

Upload dist/browser/forms.global.js from the release you use as assets/forms.global.js, load it once in layout/theme.liquid, and bind each section’s form in a small theme script. The standalone file already includes the formatter.

<script src="{{ 'forms.global.js' | asset_url }}" defer></script>
<script src="{{ 'forms-sections.js' | asset_url }}" defer></script>
const controllers = new Map()

const mount = root => {
  for (const element of root.querySelectorAll('form[data-forms]')) {
    if (controllers.has(element)) continue
    const controller = window.Forms.form(element, { validators: { email: { required: true } } })
    controllers.set(element, controller)
  }
}
const unmount = root => {
  for (const [element, controller] of controllers) {
    if (!root.contains(element)) continue
    controller.destroy()
    controllers.delete(element)
  }
}

mount(document)
document.addEventListener('shopify:section:load', event => mount(event.target))
document.addEventListener('shopify:section:unload', event => unmount(event.target))

Give each section’s form data-forms and unique field ids, for example id="email-{{ section.id }}". The theme editor’s section events keep one controller per form. Shopify’s own customer and contact forms post to Shopify; use onSubmit(callback, false) to validate first and let the native submit continue. See Shopify section events.

WordPress

Register the standalone script once and enqueue a small integration that depends on it. Pin the version you tested.

<?php
/**
 * Plugin Name: Forms example
 */
add_action('wp_enqueue_scripts', function () {
  wp_register_script(
    'samline-forms',
    'https://cdn.jsdelivr.net/npm/@samline/forms@3.0.0/dist/browser/forms.global.js',
    [],
    '2.11.1',
    ['strategy' => 'defer']
  );
  wp_enqueue_script(
    'forms-example',
    plugins_url('assets/forms-example.js', __FILE__),
    ['samline-forms'],
    '1.0.0',
    ['strategy' => 'defer']
  );
});
for (const element of document.querySelectorAll('form[data-forms]')) {
  window.Forms.form(element, { validators: { email: { required: true } } })
}

The strategy argument requires WordPress 6.3+. Add data-forms to the forms you want to enhance (a custom block, a template part or a form plugin’s markup filter). Validate submitted data again in PHP: client rules improve the experience, they do not protect your server.

Plain HTML and server-rendered templates

Use HTML / CDN with the same API. For classic Blade, ERB or Twig forms that post to the server, register onSubmit(callback, false) or no handler at all: valid submits navigate normally, invalid ones are stopped with focus on the first error.