A form as an Astro island
What it combines
<HubForm>— fetches a form schema from the Saastro ingestion endpoint and submits back to itinitialSchema— a schema the host already fetched, so the first render is the form and not a “Loading…” placeholder- An Astro island — a React component hydrated on the client with
client:load(orclient:visible)
The form renders from initialSchema with no schema request. Submit it: the demo intercepts the request and shows the body the island would send.
import { FormBuilder, HubForm } from '@saastro/forms';
/**
* What `https://submit.saastro.io/v1/<siteId>/<formSlug>.json` returns: a plain,
* serialisable form config. In a real page you fetch it in the `.astro`
* frontmatter (see index.mdx); here it is built locally so the demo needs no network.
*/
export function createSchema() {
const config = FormBuilder.create('newsletter')
.layout('manual')
.columns(12)
.addField('email', (f) =>
f.type('email').label('Email').required().email().columns({ default: 12 }),
)
.addField('topic', (f) =>
f
.type('select')
.label('Topic')
.required()
.options([
{ value: 'product', label: 'Product news' },
{ value: 'engineering', label: 'Engineering' },
])
.columns({ default: 12 }),
)
.addStep('subscribe', ['email', 'topic'])
.initialStep('subscribe')
.build();
// The Hub serves JSON: drop anything a JSON round trip would lose.
return JSON.parse(JSON.stringify(config)) as unknown;
}
/**
* The island. Astro hydrates it on the client; because `initialSchema` is set,
* the very first render (and the server-rendered HTML) already contains the form
* and no schema request is made.
*/
export function NewsletterIsland({
schema,
hubUrl,
components,
}: {
schema: unknown;
hubUrl?: string;
/** Primitive UI components. Functions cannot cross an island boundary as props: import them here. */
components?: Record<string, unknown>;
}) {
return (
<HubForm
siteId="my-site"
formSlug="newsletter"
hubUrl={hubUrl}
initialSchema={schema}
formProps={components ? { components: components as never } : undefined}
/>
);
}The code
The Code tab above has the island (NewsletterIsland) and a local createSchema() that stands in for the Hub’s JSON. In a real Astro page you fetch the schema in the frontmatter, which runs on the server for every request:
---
// src/pages/newsletter.astro
import { NewsletterIsland } from '../components/NewsletterIsland';
const res = await fetch('https://submit.saastro.io/v1/my-site/newsletter.json');
// `null` means "the host tried and failed": the island falls back to fetching on the client.
const schema = res.ok ? await res.json() : null;
---
<NewsletterIsland client:load schema={schema} />
How it works
- Server render —
<HubForm>fetches inside an effect, and effects do not run during server rendering. WithoutinitialSchemathe HTML would contain only the loading fallback. With it, the first render is alreadyready, so the form is in the HTML and hydration only attaches handlers. - No request on load — when
initialSchemais present no schemaGETis issued.siteId,formSlugandhubUrlare then used only to build the submit handler. - Same checks — the schema still goes through the renderable check: one without fields or steps shows the “unconfigured” banner.
- Submit — the form posts to
<hubUrl>/<siteId>/<formSlug>/submitand shows the success panel when the response is{ ok: true }.
Caveats
- Components cannot be props — Astro serialises island props, and functions and components don’t survive that. Import your UI primitives inside the island file (or wrap it in a provider there) and pass only data from the
.astrofile. - Schema must be JSON — pass what the endpoint returned, not a config built with Zod schemas or handlers.
- Hydration directive —
client:loadhydrates immediately;client:visiblewaits until the form is on screen, and until then the server-rendered form is not interactive. - Failed fetch — pass
nullso the island retries from the browser, and keep anerrorFallbackfor when that fails too.
Variations
- Use
client:only="react"if you do not need the server-rendered HTML; theninitialSchemais optional. - Add
plugins={[localStoragePlugin]}to<HubForm>to resume a half-filled form — see Save and continue later. - Set
localeto the page language to render a translated form.