- Docs
- Framework integrations
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
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
<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
<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
useEffectand destroys it in the cleanup, which also handles the development double-mount of Strict Mode. If you need a controlled input, write changes throughcontroller.setValue()so validation and watchers run. - Vue creates it in
onMountedand destroys it inonBeforeUnmount. - 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.