# Astro Utils — complete documentation

Generated from the same source as the website. Begin with /docs/llms.txt for focused retrieval.

# Build with Astro Utils

Start here when implementing an Astro Utils feature. These instructions accompany the current documentation source; check your installed package versions before relying on an API. Browser previews simulate server behavior and do not demonstrate a deployed backend.

## Choose the utility

- Forms: bound fields, validation, server callbacks, state, sessions, and chunked uploads.
- Context: request-local values shared between Astro components. It is not persistent storage.
- Express Endpoints: middleware, request parsing, and response helpers for Astro API routes.

## Install and configure Forms

Use the complete [Forms setup](/docs/guides/forms/getting-started/index.md). Install `@astro-utils/forms` and `@astrojs/node` using npm, pnpm, Yarn, or Bun. Configure on-demand rendering, the Forms integration, middleware, and one shared `WebForms` layout. The exact setup files are included below.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

For deployment, follow [configuration](/docs/reference/forms/configuration/index.md) and supply a stable environment secret. Do not commit secrets. Sessions are signed, not encrypted; do not treat them as permanent application storage.

## Build the product filter

This complete example uses a local catalog and requires no database. Copy the files to their labeled paths. Run your project's `dev` script, open `/products`, and submit budgets of 10, 50, and 100. Expect zero, two, and three results. Negative and empty budgets must fail validation.

### src/pages/products.astro

```astro title="src/pages/products.astro"
---
import { BButton, BInput, Bind, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';
import { products } from '../data/products';

const bind = Bind({ maxPrice: 50 });
let matches = products.filter(product => product.price <= bind.maxPrice);

function filterProducts() {
    matches = products.filter(product => product.price <= bind.maxPrice);
}
---
<Layout>
    <span slot="title">Filter products</span>
    <BindForm {bind}>
        <label for="maxPrice">Maximum price ($)</label>
        <BInput id="maxPrice" name="maxPrice" type="number" min={0} required />

        <BButton onClick={filterProducts} whenFormOK>Apply filter</BButton>
        
        <p role="status">{matches.length} products found</p>
        <ul>{matches.map(product => <li>{product.name} — ${product.price}</li>)}</ul>
    </BindForm>
</Layout>
```

### src/data/products.ts

```ts title="src/data/products.ts"
// A local catalog keeps this example runnable without a database.
// Replace the filter in your server callback with your application's query.
export const products = [
    { name: 'Notebook', price: 12 },
    { name: 'Desk lamp', price: 35 },
    { name: 'Headphones', price: 79 }
];
```

## Build the homepage collection search

This example searches an Astro content collection on the server. It does not make a live database query. For database-backed products, replace `getCollection` with your application's database query inside the callback; do not assume an unspecified database client exists.

Add the following collection to `src/content.config.ts`, merging it with existing collections. The inline loader makes this sample self-contained; replace it with your actual catalog source as needed.

```ts title="src/content.config.ts"
import { defineCollection, z } from 'astro:content';
const products = defineCollection({
    loader: async () => [
        { id: 'notebook', name: 'Notebook', price: 12 },
        { id: 'lamp', name: 'Desk lamp', price: 35 },
        { id: 'headphones', name: 'Headphones', price: 79 }
    ],
    schema: z.object({ name: z.string(), price: z.number() })
});
export const collections = { products };
```

```astro title="src/pages/search.astro"
---
import { getCollection } from "astro:content";
import { Bind, BindForm, BInput, BButton } from "@astro-utils/forms/forms.js";
import Layout from "../layouts/Layout.astro";

const bind = Bind({ query: "" });

let products = await getCollection("products");

async function search() {
  products = products.filter(product => 
    product.name.toLowerCase().includes(bind.name.toLowerCase())
  );
}
---

<Layout>
  <BindForm {bind}>
    <label for="query">Find a product</label>

    <BInput id="query" name="query" />
    <BButton onClick={search}>Search</BButton>

    <p>{products.length} products found</p>

    <ul>
      {products.map(({ data }) => <li>{data.name} — ${data.price}</li>)}
    </ul>
  </BindForm>
</Layout>
```

Run `astro sync` to generate collection types, then your project's `dev` script. Open `/search`. Search “lamp” to see Desk lamp, an unknown name for no results, and clear the field to show the whole collection.

## Execution and state

`WebForms` handles the submission. `BindForm` restores bound values, bound controls validate input, and a button invokes its server callback. `whenFormOK` restricts callbacks to valid submissions. Astro then renders the updated result. A request-local variable is not durable state. Use bound state, sessions, or application storage according to the lifetime you need.

## Find the right recipe

- [Binding and validation](/docs/guides/forms/data-binding/index.md)
- [Tasks](/docs/examples/todo/index.md)
- [Preferences](/docs/examples/settings/index.md)
- [Upload progress](/docs/examples/upload/index.md)
- [Draft service requests](/docs/examples/government-form/index.md)
- [Login feedback](/docs/examples/login/index.md): illustrative demo credentials, not production authentication.
- [Account fields](/docs/examples/signup/index.md): does not create real database accounts.
- [Context](/docs/guides/context/index.md)
- [HTTP endpoints](/docs/guides/express-endpoints/index.md)
- [All documentation](/docs/llms.txt)

## Check your implementation

1. Verify imports against the relevant API reference; do not invent events or component props.
2. Run `astro check` and your project's build. Test the real server route, not only a documentation preview.
3. Exercise successful submission, invalid input, empty results, and repeated submissions.
4. Confirm which state survives a request or reload. Keep passwords out of persisted view state.
5. For uploads, test interruption and retry; the progress component's `for` value matches the field name.
6. Confirm any external database, authentication, or storage service separately. Static snippet compilation does not certify those integrations.


---

# Submit a service request

Grouped fields, draft saving, and final validation.

Source: https://withastro-utils.github.io/docs/examples/government-form/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Save an incomplete draft, then finish the required fields and submit. The preview confirms each action; it does not persist a draft after reload.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/application.astro

```astro title="src/pages/application.astro"
---
import { BButton, BInput, BOption, BSelect, BTextarea, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

type Form = {
    application: { 
        legalName: string; 
        birthDate: string | Date; service: 
        string; details: string 
    }
};

const bind = Bind<Form>({application: Astro.locals.session.applicationDraft});
let status = '';

function saveDraft() {
    Astro.locals.session.applicationDraft = bind.application;
    status = 'Draft saved.';
}

async function submitApplication() {
    await sendData(bind.application);
    status = 'Application submitted.';

    Astro.locals.session.applicationDraft = undefined;
    bind.application = {}; // clear the form
}
---
<Layout>
    <span slot="title">Submit a service request</span>

    <BindForm {bind}>
        <FormErrors title="Check your application" />

        <fieldset>
            <legend>Applicant details</legend>

            <label for="legalName">Legal name</label>
            <BInput id="legalName" name="application.legalName" autocomplete="name" maxlength={60} required />

            <label for="birthDate">Date of birth</label>
            <BInput id="birthDate" name="application.birthDate" type="date" required />
        </fieldset>

        <fieldset>
            <legend>Request</legend>

            <label for="service">Service</label>
            <BSelect id="service" name="application.service">
                <BOption value="permit">Permit application</BOption>
                <BOption value="record">Public record request</BOption>
            </BSelect>

            <label for="details">Supporting details</label>
            <BTextarea id="details" name="application.details" maxlength={600} required />
        </fieldset>

        <BButton onClick={saveDraft}>Save draft</BButton>
        <BButton onClick={submitApplication} whenFormOK>Submit application</BButton>

        {status && <p role="status">{status}</p>}
    </BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

In your project, **Save draft** writes a small object to the current session. Reloading the page restores it; submission clears it. This identifies the draft by browser session, not by an authenticated account. For a real service, authenticate the applicant and store drafts durably under their user ID. The demo creates no official request.

## Continue

Review [binding and validation](https://withastro-utils.github.io/docs/guides/forms/data-binding/index.md).

---

# Examples

Explore complete Astro Utils source with interactive previews for accounts, tasks, settings, uploads, and service requests.

Source: https://withastro-utils.github.io/docs/examples/

Choose a pattern, inspect the source, then open **Preview** to try it. Previews simulate server behavior locally.

- [Create an account](https://withastro-utils.github.io/docs/examples/signup/index.md): Bind account fields, validate them, and run a server action after a valid submission.
- [Log in with feedback](https://withastro-utils.github.io/docs/examples/login/index.md): Try success and error feedback with a clearly labeled demo session.
- [Manage a task list](https://withastro-utils.github.io/docs/examples/todo/index.md): Add and remove persisted items while the form automatically renders the latest server state.
- [Edit profile settings](https://withastro-utils.github.io/docs/examples/settings/index.md): Combine text, select, and textarea controls in one saved preferences form.
- [Upload a large file](https://withastro-utils.github.io/docs/examples/upload/index.md): Upload a file in bounded chunks and show progress before processing it on the server.
- [Submit a service request](https://withastro-utils.github.io/docs/examples/government-form/index.md): Group an application into sections and save a small draft in the session.
- [Filter a product catalog](https://withastro-utils.github.io/docs/examples/products/index.md): Bind a price filter, run server logic, and render matching products.

## Filter products with a server action

[Explore the product-filter workspace](https://withastro-utils.github.io/docs/examples/products/index.md): bind a price field, filter a catalog, and render the matching rows in one Astro component.

---

# Log in with feedback

Success, error feedback, and session updates.

Source: https://withastro-utils.github.io/docs/examples/login/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Use **demo@example.com** and **demo-only** for success. Any other credentials show an error. Try an error followed by success to see feedback reset.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/login.astro

```astro title="src/pages/login.astro"
---
import { BButton, BInput, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

const bind = Bind({ email: '', password: '' });

let error = '';
let message = '';

function logIn() {
    if (bind.email !== 'demo@example.com' || bind.password !== 'demo-only') {
        error = 'Email or password is incorrect.';
    } else {
        Astro.locals.session.demoUserId = 'demo-user';
        message = 'Signed in to the demo.';
    }
}
---
<Layout>
    <span slot="title">Log in with feedback</span>
    <BindForm {bind} omitState={['password']}>
        <FormErrors />

        {error && <p role="alert">{error}</p>}
        {message && <p role="status">{message}</p>}

        <label for="email">Email</label>
        <BInput id="email" name="email" type="email" autocomplete="email" required />

        <label for="password">Password</label>
        <BInput id="password" name="password" type="password" autocomplete="current-password" required />

        <BButton onClick={logIn} whenFormOK>Log in</BButton>
    </BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

These public credentials demonstrate the form flow only. Replace the demo condition with your authentication provider before using this in an application. Passwords are excluded from view state; the callback clears the submitted value. Only the demo user ID is saved in the session.

## Continue

Read the [session reference](https://withastro-utils.github.io/docs/reference/forms/session/index.md).

---

# Filter a product catalog

Bound input, server-side filtering, and updated results in one Astro component.

Source: https://withastro-utils.github.io/docs/examples/products/

Query on the server. Render in the same component. This example uses a small local catalog so you can run it without a database; replace the filter callback with your own database query when connecting real products.

## Try the interaction

Set a maximum price and apply the filter. Try **10** for no results, **50** for two products, or **100** for the full catalog. Negative and empty prices are rejected.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/products.astro

```astro title="src/pages/products.astro"
---
import { BButton, BInput, Bind, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';
import { products } from '../data/products';

const bind = Bind({ maxPrice: 50 });
let matches = products.filter(product => product.price <= bind.maxPrice);

function filterProducts() {
    matches = products.filter(product => product.price <= bind.maxPrice);
}
---
<Layout>
    <span slot="title">Filter products</span>
    <BindForm {bind}>
        <label for="maxPrice">Maximum price ($)</label>
        <BInput id="maxPrice" name="maxPrice" type="number" min={0} required />

        <BButton onClick={filterProducts} whenFormOK>Apply filter</BButton>
        
        <p role="status">{matches.length} products found</p>
        <ul>{matches.map(product => <li>{product.name} — ${product.price}</li>)}</ul>
    </BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

### src/data/products.ts

```ts title="src/data/products.ts"
// A local catalog keeps this example runnable without a database.
// Replace the filter in your server callback with your application's query.
export const products = [
    { name: 'Notebook', price: 12 },
    { name: 'Desk lamp', price: 35 },
    { name: 'Headphones', price: 79 }
];
```

## How it works

`Bind` restores the submitted budget, `BInput` validates the field, and `BButton` runs `filterProducts` on the server when the form is valid. Astro renders the result count and matching rows together. The embedded preview simulates this interaction locally.

## Run it yourself

Follow the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) or copy the configuration, middleware, and shared layout from the file sidebar. Add both the page and catalog files at the paths shown.

---

# Edit profile settings

Text, select, and textarea fields in one form.

Source: https://withastro-utils.github.io/docs/examples/settings/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Change the name, language, and bio, then save. In your own project, reload the page to see the session-backed values restored.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/settings.astro

```astro title="src/pages/settings.astro"
---
import { BButton, BInput, BOption, BSelect, BTextarea, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

type Preferences = { name: string; locale: string; bio: string };

const bind = Bind<Preferences>(Astro.locals.session.preferences ?? { name: 'Ari Chen', locale: 'en', bio: '' });
let saved = false;

function savePreferences() {
    Astro.locals.session.preferences = { name: bind.name, locale: bind.locale, bio: bind.bio };
    saved = true;
}
---
<Layout>
    <span slot="title">Edit profile settings</span>
    <BindForm {bind}>
        <FormErrors />

        {saved && <p role="status">Preferences saved.</p>}

        <label for="name">Display name</label>
        <BInput id="name" name="name" maxlength={40} required />

        <label for="locale">Language</label>
        <BSelect id="locale" name="locale">
            <BOption value="en">English</BOption>
            <BOption value="es">Spanish</BOption>
            <BOption value="fr">French</BOption>
        </BSelect>

        <label for="bio">Bio</label>
        <BTextarea id="bio" name="bio" maxlength={180} />
        
        <BButton onClick={savePreferences} whenFormOK>Save changes</BButton>
    </BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

The source reads and writes a small preferences object through `Astro.locals.session`. The embedded preview only demonstrates the controls and save feedback. Use application storage for preferences that must survive session expiry or work across devices.

## Continue

Explore the [input component reference](https://withastro-utils.github.io/docs/reference/forms/basic-form-components/index.md).

---

# Create an account

Account fields and valid-only actions.

Source: https://withastro-utils.github.io/docs/examples/signup/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Enter a name and email, then submit. An invalid email is rejected before the action runs.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/signup.astro

```astro title="src/pages/signup.astro"
---
import { BButton, BInput, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

const bind = Bind({ name: '', email: '' });
let message = '';

function signUp() {
    try {
        signupUser({ name: bind.name, email: bind.email });
        message = `Account details received for ${bind.email}.`;

        bind.defaults();
        Astro.locals.forms.redirectTimeoutSeconds('/', 2); // demo - not redirecting
    } catch (error){
        message = `Error: ${error.message}`;
    }
}
---
<Layout>
    <span slot="title">Create an account</span>
    <BindForm {bind}>
        <FormErrors />
        
        <label for="name">Name</label>
        <BInput id="name" name="name" required maxlength={40} />

        <label for="email">Email</label>
        <BInput id="email" name="email" type="email" required maxlength={120} />

        <BButton onClick={signUp} whenFormOK>Create account</BButton>
        {message && <p role="status">{message}</p>}
    </BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

The runnable source stores the submitted details in the signed session. It does not create a database account or send an email. Replace that small callback with your account service once the form works.

## Continue

Learn how to [show custom validation errors](https://withastro-utils.github.io/docs/guides/forms/data-binding/index.md#validate-a-reserved-name).

---

# Manage a task list

Adding and removing repeated items.

Source: https://withastro-utils.github.io/docs/examples/todo/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Add a task, then remove it. Removal does not require a valid value in the new-task field.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/todo.astro

```astro title="src/pages/todo.astro"
---
import { BButton, BInput, Bind, BindForm } from '@astro-utils/forms/forms.js';

import Layout from '../layouts/Layout.astro';

type TaskForm = {
    newTask: string;
    message: string;
};

type TodoTask = {
    title: string;
    id: string;
}

const bind = Bind<TaskForm>({ newTask: '', message: '' });
const tasks: TodoTask[] = Astro.locals.session.tasks ??= [{ id: 'limits', title: 'Review upload limits' }, { id: 'notes', title: 'Publish migration notes' }];

async function addTask() {
    tasks.push({title: bind.newTask, id: crypto.randomUUID()});

    bind.message = `${bind.newTask} added.`;
    bind.newTask = '';
}

async function removeTask(id: string, title: string) {
    const index = tasks.findIndex(task => task.id === id);
    if (index === -1) {
        bind.message = 'This task has already been removed.';
        return;
    }
    tasks.splice(index, 1);

    bind.message = `${title} removed.`;
}
---

<Layout>
<span slot="title">Manage a task list</span>
<BindForm {bind} omitState={['message']}> <!-- omitState = ensure this info will be removed in the next action -->
    {bind.message && <p role="status">{bind.message}</p>}

    <label for="newTask">New task</label>
    <BInput id="newTask" name="newTask" minlength={2} maxlength={80} required />
    <BButton onClick={addTask} whenFormOK>Add task</BButton>

    <ul>
        {tasks.map(task => (
            <li>
                <span>{task.title}</span>
                <BButton onClick={() => removeTask(task.id, task.title)}>Remove</BButton>
            </li>
        ))}
    </ul>
</BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

The runnable source stores a small list in the signed session cookie. It survives page reloads while that session remains valid; it is not shared between devices. Keep the list small or move it to application storage. The removal handler checks that the item still exists before changing the list.

## Continue

Learn about [stable keys and reusable components](https://withastro-utils.github.io/docs/guides/forms/loops-and-components/index.md).

---

# Upload a large file

Chunked transfer, progress, and completion feedback.

Source: https://withastro-utils.github.io/docs/examples/upload/

Complete the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) first, or use the configuration, middleware, and layout files in the sidebar. Install `@astro-utils/forms` and `@astrojs/node` in an existing Astro project.

## Try the interaction

Select a file and upload it. Use the preview’s **Simulate upload failure** option to compare success with a retryable error.

### src/layouts/Layout.astro

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

### src/pages/upload.astro

```astro title="src/pages/upload.astro"
---
import { type BigFile, BButton, Bind, BindForm, FormErrors, UploadBigFile, UploadBigFileProgress } from '@astro-utils/forms/forms.js';

import Layout from '../layouts/Layout.astro';

type UploadForm = {
    file: BigFile;
};

const bind = Bind<UploadForm>();
let message = '';

async function saveFile() {
    message = `${bind.file.name} is ready.`;
}
---

<Layout>
<span slot="title">Upload a large file</span>
<BindForm {bind}>
    <FormErrors />
    {message && <p role="status">{message}</p>}

    <label for="file">Project archive</label>
    <UploadBigFile id="document" name="file" required />
    <UploadBigFileProgress for="file" />
    
    <BButton onClick={saveFile} whenFormOK>Upload file</BButton>
</BindForm>
</Layout>
```

### src/middleware.ts

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

### astro.config.mjs

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## How it works

The source uploads the selected file and reports its metadata. Add your application processing in `saveFile`. The embedded preview simulates transfer progress and never sends your file to a server.

`UploadBigFileProgress for="file"` matches the upload control’s `name="file"`, even when its HTML ID is `document`. Every `BButton` submits its containing form, so put actions that must not upload the selected file outside that form. See [upload limits and failure handling](https://withastro-utils.github.io/docs/reference/forms/upload-big-file/index.md#configure-upload-limits).

## Continue

Review [Forms configuration](https://withastro-utils.github.io/docs/reference/forms/configuration/index.md).

---

# Context quickstart

Share a value between a layout and a nested component.

Source: https://withastro-utils.github.io/docs/guides/context/

Context passes values to nested Astro components without forwarding a prop through every intermediate component. It exists during a render; it is not a browser store or persistent session.

## Install Context

```sh title="Terminal"
npm install @astro-utils/context
```

```sh title="Terminal"
pnpm add @astro-utils/context
```

```sh title="Terminal"
yarn add @astro-utils/context
```

```sh title="Terminal"
bun add @astro-utils/context
```

## Provide a named value

```astro title="src/pages/index.astro"
---
import Context from '@astro-utils/context/Context.astro';

const user = await fetchUser();

---
<Context contextName="user" {user}>
   <Layout title="Home Page">
        <h1>This is home page</h1>

        <Button>This is your themed button!</Button>
   </Layout> 
</Context>
```

## Every layout/component can use it

```astro title="src/components/Button.astro"
---
import getContext from '@astro-utils/context';
const { user } = getContext(Astro, 'user');

---
<button class={user?.themes?.button}>Click me</button>
```

```astro title="src/layout/Website.astro"
---
import getContext from '@astro-utils/context';

const { title } = Astro.props;

const { user } = getContext(Astro, 'user');
---
<html lang="en">
    <head>
        <title>{title}</title>
    </head>
    <body>
        <p>{user ? "User logged in" : "User not logged in"}</p>

        </slot>
    </body>
</html>
```

## Nested values

A nested provider with the same `contextName` inherits the outer values and overrides the props it supplies (extends and override). An absent context returns `{}`.

See [Context API](https://withastro-utils.github.io/docs/reference/context/index.md) for manual async rendering and the prop reference.

---

# Express Endpoints quickstart

Create and call an Astro API route with Express-style request and response helpers.

Source: https://withastro-utils.github.io/docs/guides/express-endpoints/

Use Express-style routing and middleware in an Astro API endpoint. This example accepts JSON and returns a greeting.

## Install the package and adapter

```sh title="Terminal"
npm install @astro-utils/express-endpoints @astrojs/node
```

```sh title="Terminal"
pnpm add @astro-utils/express-endpoints @astrojs/node
```

```sh title="Terminal"
yarn add @astro-utils/express-endpoints @astrojs/node
```

```sh title="Terminal"
bun add @astro-utils/express-endpoints @astrojs/node
```

## Enable server rendering

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({ 
    output: 'server', 
    adapter: node({ mode: 'standalone' }) 
});
```

## Create a route

```ts title="src/pages/api/hello.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();

router.body('json');

export const POST = router.route((req, res) => {
    const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
    if (!name) {
        res.status(400).json({ error: 'Name is required.' });
        return;
    }
    res.json({ message: `Hello, ${name}!` });
});
```

## Call it

Start your project with its `dev` script. Use the port printed by Astro in this request:

```sh title="Terminal"
curl -X POST http://localhost:4321/api/hello \
    -H 'Content-Type: application/json' \
    -d '{"name":"Alex"}'
```

The response is `{"message":"Hello, Alex!"}`. Sending `{}` returns status 400 and `{"error":"Name is required."}`. The example has no artificial delay or external service dependency.

## Parse a different body

`router.body('multipart')` makes uploaded files available on `req.filesOne` and `req.filesMany`. Use `urlencoded` for an ordinary HTML form or `text` for a text body. 
The default `auto` mode selects the parser from `Content-Type`.

See [request examples](https://withastro-utils.github.io/docs/reference/express/request/index.md) and [response examples](https://withastro-utils.github.io/docs/reference/express/response/index.md).

## Add schema validation

For schema-based validation, install the Zod major version supported by the package's [express-zod-safe](https://www.npmjs.com/package/express-zod-safe) integration:

```sh title="Terminal"
npm install zod@^4
```

```sh title="Terminal"
pnpm add zod@^4
```

```sh title="Terminal"
yarn add zod@^4
```

```sh title="Terminal"
bun add zod@^4
```

```ts title="src/pages/api/validated-hello.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';
import { z } from 'zod';

const router = new ExpressRoute();

router.validate({ 
    body: z.object({ 
        name: z.string().trim().min(1) 
    })
});

export const POST = router.route((req, res) => {
    res.json({ message: `Hello, ${req.body.name}!` });
});
```

By default, it's relax validation that ignore extra properties, defaults to:
- defaultSchemaObject: lax
- missingSchemaBehavior: any

Validation applies to the next route created by this router. Review [middleware and error handling](https://withastro-utils.github.io/docs/reference/express/router-and-errors/index.md) before composing several handlers.

---

# Binding & Validation

Using data binding with Astro Forms

Source: https://withastro-utils.github.io/docs/guides/forms/data-binding/

With Astro Forms you can easily create forms with data binding and validation. It also provides a simple way to handle form submissions and preserve state between postbacks.

## Data Binding

Astro Forms supports two-way data binding. This means that you can bind a form field to a property on `Bind` instance and the value of the property will be updated when the field changes and vice versa.

### Submit a profile

### src/pages/profile.astro

```astro title="src/pages/profile.astro"
---
import { Bind, BindForm, BButton, BInput } from "@astro-utils/forms/forms.js";
import Layout from "../layouts/Layout.astro";

type Form = {
    name: string;
    age: number;
}

const bind = Bind<Form>();

let showSubmitText = '';
function formSubmit(){
    showSubmitText = `Your name is ${bind.name}; you are ${bind.age} years old.`;
    bind.age++;
}
---
<Layout>
    <BindForm {bind}>
        {showSubmitText}

        <label for="name">What is your name?</label>
        <BInput id="name" type="text" name="name" maxlength={20} required/>

        <label for="age">Enter age</label>
        <BInput id="age" type="int" name="age" min={10} required/>

        <BButton onClick={formSubmit} whenFormOK>Submit</BButton>
    </BindForm>
</Layout>
```

In this example, the `Bind` instance is bound to the form fields.
- When the user changes the value of the `name` or `age` fields and submits, the `Bind` instance is updated.
- The `formSubmit` function will be called when the user clicks the `Submit` button and the form is valid.
- After `formSubmit` the `age` property will be incremented and the `showSubmitText` will be updated.

## Validate a reserved name

HTML constraints such as `required` and `minlength` are checked by the browser and server. A custom validator handles application rules. Try `admin` to see a server validation error; `Alex` succeeds.

```astro title="src/pages/choose-name.astro"
---
import { BButton, BInput, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

const bind = Bind({ name: '' });
let saved = false;

function validateName(value: string) {
    if (['admin', 'support'].includes(value.trim().toLowerCase())) {
        return { error: 'Choose a name other than admin or support.' };
    }
}

function save() {
     saved = true;
}
---
<Layout>
    <span slot="title">Choose a name</span>
    <BindForm {bind}>
        <FormErrors />

        <label for="name">Display name</label>
        <BInput id="name" name="name" required minlength={2} validate={validateName} />
        
        <BButton onClick={save} whenFormOK>Save name</BButton>
        {saved && <p role="status">Name accepted: {bind.name}</p>}
    </BindForm>
</Layout>
```

Return `{ error }` to reject a value, or return nothing to accept it. `FormErrors` renders the feedback; `whenFormOK` prevents `save` from running on invalid input. See the [validation contract](https://withastro-utils.github.io/docs/reference/forms/data-binding/index.md#custom-validation).

## View State

Astro Forms also supports view state. This means that the values of the form fields will be preserved between postbacks.

### Keep a counter between submissions

### src/pages/counter.astro

```astro title="src/pages/counter.astro"
---
import { Bind, BindForm, BButton } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

type Form = {
    counter: number;
}

const bind = Bind<Form>({counter: 0});

function incCounter(){
    bind.counter++;
}
---
<Layout>
    <BindForm {bind}>
        Counter: {bind.counter}

        <BButton onClick={incCounter}>Increase counter</BButton>
    </BindForm>
</Layout>
```

What happens here is that the `counter` property of the `Bind` instance will be incremented every time the user clicks the `Increase counter` button.

The `Bind` state persists between postbacks by storing compressed and encrypted view state on the client.

### Valid values

The state of the `Bind` instance must be serializable, but it can contain more than plain JSON values.

You can use any valid [SuperJSON](https://github.com/blitz-js/superjson) value in the `Bind` instance.
This includes `Date`, `Map`, `URL`, `Set`, `RegExp`, `BigInt`, `undefined` are supported.

### Button State

You can use state per `BButton` component. You can also change the `BButton` props easily each time the button is clicked.

Special props:
- **state**: any - store state per button
- **extra**: any - store extra data per button (cannot be changed in the `onClick` function)
- **innerText**: string - the text of the button (overrides the children)
- **innerHTML**: string - the HTML of the button (overrides the children)
- **remove**: boolean - remove the button from the HTML
- **reset()**: function - reset the button to the initial state
- **defaults**: any - the default state of the button

### src/pages/button-colors.astro

```astro title="src/pages/button-colors.astro"
---
import { BButton, Bind, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

const colors = ['red', 'green', 'blue', 'yellow', 'purple', 'orange', 'pink', 'black', 'white', 'gray'];

function changeColor() {
    this.state.color++;

    if (this.state.color >= colors.length) {
        this.state.color = this.extra;
    }
    this.style = `color: ${colors[this.state.color]}`;
}
---

<Layout>
    <BindForm>
        {
            colors.map((_, i) => (
                <BButton onClick={changeColor} extra={i} state={{ color: i }}>
                    Button {i}
                </BButton>
            ))
        }
    </BindForm>
</Layout>
```

In this example, the `changeColor` will change the button color each time it is clicked to another color in the `colors` array.

If the button is clicked more times than the length of the `colors` array, it starts from the beginning.

---

# Getting Started

Install Astro Utils Forms and run a complete server action without an external service.

Source: https://withastro-utils.github.io/docs/guides/forms/getting-started/

Build a form that sends a name to your server and renders a greeting. Start inside an existing Astro project; no database or email provider is needed.

**Use server rendering**

Forms need on-demand rendering. This guide configures the Node adapter and a single `WebForms` root.

## 1. Install Forms and the adapter

```sh title="Terminal"
npm install @astro-utils/forms @astrojs/node
```

```sh title="Terminal"
pnpm add @astro-utils/forms @astrojs/node
```

```sh title="Terminal"
yarn add @astro-utils/forms @astrojs/node
```

```sh title="Terminal"
bun add @astro-utils/forms @astrojs/node
```

## 2. Configure Astro

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
    output: 'server',
    adapter: node({ mode: 'standalone' }),
    integrations: [forms]
});
```

## 3. Add middleware

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

The default is enough for local development. For deployed projects, pass a stable environment secret through the [middleware configuration](https://withastro-utils.github.io/docs/reference/forms/configuration/index.md). Keep it stable across restarts and out of source control. For an existing middleware chain, compose this middleware with Astro's `sequence()` helper.

## 4. Add the shared layout

Use one `WebForms` root around your form content. The examples throughout these docs import this layout.

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

## 5. Create your first form

Save the following page as `src/pages/hello.astro`. **Preview** simulates the same interaction inside the docs; running the page in your own project executes the callback on your server.

### src/pages/hello.astro

```astro title="src/pages/hello.astro"
---
import { BButton, BInput, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

const bind = Bind({ name: '' });
let message = '';

function greet() {
    message = `Hello, ${bind.name}! Your server action ran.`;
}
---
<Layout>
    <span slot="title">Your first form</span>
    <BindForm {bind}>
        <FormErrors />
        
        <label for="name">Your name</label>
        <BInput id="name" name="name" required maxlength={40} />

        <BButton onClick={greet} whenFormOK>Say hello</BButton>
        {message && <p role="status">{message}</p>}
    </BindForm>
</Layout>
```

## 6. Run it

Start your Astro project with your package manager's `dev` script. Open `/hello` on the URL printed by Astro, enter a name, and select **Say hello**. You should see **Hello, Alex! Your server action ran.** when you enter Alex. An empty name prevents the valid-only callback.

## What happens on submit

1. `WebForms` receives the POST request.
2. `BindForm` restores state and validates the submitted controls.
3. `BButton` calls `greet` when validation succeeds.
4. The form renders again with the updated message.

`message` is request-local feedback. Use `omitState` when feedback is stored on `bind` but should not persist into the next submission.

## Next steps

Learn [binding and validation](https://withastro-utils.github.io/docs/guides/forms/data-binding/index.md), or adapt the [account example](https://withastro-utils.github.io/docs/examples/signup/index.md) to your application. If the action does not run, check server rendering, middleware, the integration, and the `WebForms` layout first.

---

# Server Helpers

Redirect after a form action, refresh a parent form, and update the browser.

Source: https://withastro-utils.github.io/docs/guides/forms/js-helpers/

Use `Astro.locals.forms` inside a Forms page with the [shared setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md).

## Show feedback before redirecting

```astro title="src/pages/finish.astro"
---
import { BButton, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

let message = '';

function finish() {
    message = 'Done. Returning to the home page in two seconds.';
    Astro.locals.forms.redirectTimeoutSeconds('/', 2);
}
---
<Layout>
    <span slot="title">Finish a task</span>
    <BindForm>
        <BButton onClick={finish}>Finish</BButton>
        <p role="status">{message}</p>
    </BindForm>
</Layout>
```

`redirectTimeoutSeconds` sends a browser action, so the user sees the rendered feedback before navigating. Use `redirect('/account')` in the callback when you want an immediate HTTP redirect instead.

## Refresh a parent after a child action

A form rerenders after its own action. Call `reloadState()` only when a nested form changes data shown by its parent. The [editable users example](https://withastro-utils.github.io/docs/guides/forms/loops-and-components/index.md) demonstrates deletion and the parent's count updating together.

For database-backed parent data, attach a loader to `bind.on.reloadState`. A reload does not run the original button callback again.

## Choose a helper

| Helper | Use it for |
| --- | --- |
| `redirect(url, status?)` | An immediate server redirect. |
| `redirectTimeoutSeconds(url, seconds?)` | Render feedback, then navigate in the browser. |
| `reloadState()` | Rerender a parent affected by a child action. |
| `updateSearchParams()` | Change several URL query values, then call the returned `redirect()`. |
| `updateOneSearchParam(key, value?, status?)` | Change or remove one query value and redirect. |
| `alert(message)` | Show a browser alert. Prefer inline feedback for ordinary validation. |
| `consoleLog(...values)` / `console(type, ...values)` | Log in the browser. |
| `callFunction(name, ...args)` | Call an existing browser function. |

## Stop a nested operation with a response

Use [ThrowOverrideResponse](https://withastro-utils.github.io/docs/reference/forms/advanced-responses/index.md) when a nested function must stop processing and return a response. Setting a redirect and throwing a response serve different control-flow needs; ordinary form callbacks usually only need the redirect helper.

---

# Loops & Reusable Components

Keep each repeated form attached to the right item when a list changes.

Source: https://withastro-utils.github.io/docs/guides/forms/loops-and-components/

Start with the [shared Forms layout and middleware](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md). These two files make a small editable list stored in the browser's Forms session.

## Render a list of forms

```astro title="src/pages/users.astro"
---
import { BButton, Bind, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';
import UserItem from '../components/UserItem.astro';

type User = { 
    id: string; 
    name: string;
};

const users: User[] = Astro.locals.session.users ??= [{ id: 'first', name: 'Alex' }];

const bind = Bind({});

function addUser() {
    users.push({ id: crypto.randomUUID(), name: 'New user' });
}
---
<Layout>
    <span slot="title">Edit users</span>
    <BindForm {bind}>
        <p>Users: {users.length}</p>
        <BButton onClick={addUser}>Add user</BButton>
        {users.map(user => <UserItem {user} />)}
    </BindForm>
</Layout>
```

## Give each item a stable key

```astro title="src/components/UserItem.astro"
---
import { BButton, BInput, Bind, BindForm, FormErrors } from '@astro-utils/forms/forms.js';

interface Props {
     user: { id: string; name: string } 
}
const { user } = Astro.props;

const bind = Bind({ name: user.name });
let saved = false;

function saveUser() {
    user.name = bind.name;
    saved = true;
}

function deleteUser() {
    const users: Props['user'][] = Astro.locals.session.users;
    const index = users.findIndex(item => item.id === user.id);

    if (index !== -1) users.splice(index, 1);
    Astro.locals.forms.reloadState(); // reloads the parent BindForm (until the top)
}
---
<BindForm {bind} key={user.id}>

    <FormErrors />
    <label for={`name-${user.id}`}>Name</label>
    <BInput id={`name-${user.id}`} name="name" required maxlength={40} />

    <BButton onClick={saveUser} whenFormOK>Save</BButton>
    <BButton onClick={deleteUser}>Delete</BButton>

    {saved && <p role="status">Saved!</p>}
</BindForm>
```

## Try adding and removing items

Open `/users`, add two users, edit their names, and delete the first user. The remaining form must keep its own name and actions.

`key={user.id}` ties each child form to the item instead of its current position. 

Do not use the array index as the key when items can be inserted, removed, or reordered. Ordinary static components and loops do not need an explicit key.

Saving a child renders that child again. Deleting changes the parent's list, so `reloadState()` requests a parent rerender and updates the count. If parent data comes from a database, reload it in the parent bind's `on.reloadState` callback before rendering.

Keep the JWT (cookie session) small. For a larger list, use durable storage and fetch only the items shown on the page.

---

# Server-first forms for Astro

Build Astro forms with server-side validation, data binding, state, and server actions. Explore examples, request context, and Express-style endpoints.

Source: https://withastro-utils.github.io/docs/

Astro Utils provides server-first forms, request context, and Express-style endpoints.

[Start building](https://withastro-utils.github.io/docs/agents/getting-started.md)

- [Create an account](https://withastro-utils.github.io/docs/examples/signup/index.md): Bind account fields, validate them, and run a server action after a valid submission.
- [Log in with feedback](https://withastro-utils.github.io/docs/examples/login/index.md): Try success and error feedback with a clearly labeled demo session.
- [Manage a task list](https://withastro-utils.github.io/docs/examples/todo/index.md): Add and remove persisted items while the form automatically renders the latest server state.
- [Edit profile settings](https://withastro-utils.github.io/docs/examples/settings/index.md): Combine text, select, and textarea controls in one saved preferences form.
- [Upload a large file](https://withastro-utils.github.io/docs/examples/upload/index.md): Upload a file in bounded chunks and show progress before processing it on the server.
- [Submit a service request](https://withastro-utils.github.io/docs/examples/government-form/index.md): Group an application into sections and save a small draft in the session.
- [Filter a product catalog](https://withastro-utils.github.io/docs/examples/products/index.md): Bind a price filter, run server logic, and render matching products.

---

# Context API

Context component, getContext, and asyncContext contracts for Astro Utils Context.

Source: https://withastro-utils.github.io/docs/reference/context/

## `Context`

```astro title="src/layouts/Layout.astro"
---
import Context from '@astro-utils/context/Context.astro';
---
<Context contextName="theme" color="blue">
    <slot />
</Context>
```

## `getContext(Astro, name?)`

Returns the nearest value for `name`, or `{}` when no provider is active. The default name is `"default"`.

```astro title="src/components/ContextContent.astro"
---
import getContext from '@astro-utils/context';

const theme = getContext(Astro, 'theme');
---
```

## `asyncContext(promise, Astro, options?)`

Runs an async render while the supplied context is active and always cleans it up afterward.

```astro title="src/components/ContextContent.astro"
---
import { asyncContext } from '@astro-utils/context';

const html = await asyncContext(() => Astro.slots.render('default'), Astro, {
    name: 'theme',
    context: { color: 'blue' }
});
---
```

| Option | Type | Default |
| --- | --- | --- |
| `name` | `string` | `"default"` |
| `context` | `unknown` | `Astro.props` |

Start with the [connected provider/consumer example](https://withastro-utils.github.io/docs/guides/context/index.md) before managing slot rendering manually.

---

# Request API

Parsed values and content-negotiation helpers available on ExpressRequest.

Source: https://withastro-utils.github.io/docs/reference/express/request/

## Read a JSON request

```ts title="src/pages/api/profile.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';
import z from "zod";

const router = new ExpressRoute();
router.body('json');

router.validate({
    body: z.object({
        name: z.string()
    }),
    query: z.object({
        page: z.coerce.number()
    })
});

export const POST = router.route((req, res) => {
    res.json({ 
        name: req.body.name,
        page: req.query.page ?? 1, 
        userAgent: req.get('user-agent') 
    });
});
```

## Read an uploaded file

```ts title="src/pages/api/upload-info.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();
router.body('multipart');

export const POST = router.route((req, res) => {
    if (req.error) {
        res.status(400).json({ error: 'The upload could not be parsed.' });
        return;
    }

    const file = req.filesOne.document;
    if (!file) {
        res.status(400).json({ error: 'Attach a file in the document field.' });
        return;
    }
    
    res.json({ name: file.name, bytes: file.size });
});
```

Send multipart form data with a field named `document`. Use `filesMany.document` when the field accepts several files.

## Values

| Property | Value |
| --- | --- |
| `astroContext` | Original Astro `APIContext` |
| `body` | Parsed body |
| `query`, `params`, `headers` | String maps |
| `cookies` | Parsed cookie values |
| `session`, `locals` | Values supplied by Astro middleware |
| `filesOne` | First native `File` for each multipart field |
| `filesMany` | Every native `File` for each multipart field |
| `method`, `url`, `originalUrl`, `path` | Request routing values |
| `hostname`, `subdomains`, `ip` | Connection values |
| `error` | Multipart parsing error, when present |

## Helpers

| Method | Behavior |
| --- | --- |
| `get(name)` | Gets a request header case-insensitively. |
| `header(name, fallback?)` | Gets a header with an optional fallback. |
| `is(type)` | Compares the request content type. |
| `param(name, fallback?)` | Checks params, then body, then query. |
| `accepts(types, ...types)` | Negotiates media types. |
| `acceptsCharsets(types, ...types)` | Negotiates character sets. |
| `acceptsEncodings(types, ...types)` | Negotiates encodings. |
| `acceptsLanguages(types, ...types)` | Negotiates languages. |

---

# Response API

Status, headers, bodies, redirects, files, cookies, and streaming with ExpressResponse.

Source: https://withastro-utils.github.io/docs/reference/express/response/

## Return JSON with status and headers

```ts title="src/pages/api/status.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();
export const GET = router.route((_req, res) => {
    res.status(200);
    res.set('Cache-Control', 'no-store');
    res.json({ status: 'ready', checkedAt: new Date().toISOString() });
});
```

A GET to `/api/status` returns JSON with an explicit status and cache policy. Set headers before sending the body; `json()` finishes the response.

`ExpressResponse` is a writable stream. Set status and headers before the first `write()` or `end()` call.

## Save a preference and redirect

```ts title="src/pages/api/preferences.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();
export const POST = router.route((_req, res) => {
    res.cookie('theme', 'dark', { httpOnly: true, sameSite: 'lax', path: '/', maxAge: 86400000 }); // maxAge in milliseconds
    res.redirect('/', 303);
});
```

The cookie stores a display preference, not an authentication credential. Use secure cookies when serving over HTTPS. A 303 redirects the browser to a GET after the POST.

## Stream a text response

```ts title="src/pages/api/report.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();
export const GET = router.route((_req, res) => {
    res.type('text/plain');
    res.write('Report started\n');
    res.end('Report complete\n');
});
```

Set headers before the first write, and always end the response. For a file already on disk, use `sendFile` or `attachment` instead.

## Finish a response

| Method | Behavior |
| --- | --- |
| `status(code)` | Sets `statusCode`. |
| `sendStatus(code)` | Sends the standard status text. |
| `send(body)` | Sends bytes, text, or JSON-compatible data. |
| `json(value)` | Sends JSON. |
| `html(value)` | Sends HTML. |
| `end(body?)` | Ends the response. |
| `write(chunk, encoding?)` | Starts or continues a streamed response. |
| `redirect(url, status?)` | Redirects with status 302 by default. |
| `sendFile(path)` | Streams a file and infers its content type. |
| `attachment(path, name?)` | Streams a file as a download. |

## Headers and cookies

| Method | Behavior |
| --- | --- |
| `set()` / `header()` | Sets one header or a header map. |
| `get()` / `getHeader()` | Reads a header. |
| `getHeaders()` / `getHeaderNames()` | Lists response headers. |
| `hasHeader()` / `removeHeader()` | Checks or removes a header. |
| `append()` / `appendHeader()` | Appends a header value. |
| `type(value)` | Sets a MIME content type. |
| `writeHead(code, headers?)` | Sets status and headers, then starts the response. |
| `cookie(name, value, options?)` | Appends a `Set-Cookie` header. Object values use JSON cookie encoding. |
| `clearCookie(name, options?)` | Expires a cookie. |
| `cacheControl({ minuets, days, months })` | Sets `max-age`. The public minute option is spelled `minuets`. |

`headersSent` becomes true after the response starts. Header changes and duplicate response endings then throw `ExpressError`.

---

# Router and errors

ExpressRoute middleware, body parsing, validation, route creation, and error classes.

Source: https://withastro-utils.github.io/docs/reference/express/router-and-errors/

## Compose middleware and a handler

```ts title="src/pages/api/status.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();

router.use((_req, res, next) => {
    res.set('Cache-Control', 'no-store');
    next();
});

export const GET = router.route((_req, res) => {
    res.json({ status: 'ready' });
});
```

`next()` allows the final handler to run. A middleware that sends a response should return without calling it.

## `ExpressRoute`

| Method | Behavior |
| --- | --- |
| `use(middleware)` | Appends middleware or another router and returns this router. |
| `body(type)` | Sets parsing to `auto`, `json`, `multipart`, `urlencoded`, or `text`. |
| `validate(schemas)` | Adds Zod Express validation to the next route. |
| `route(...handlers)` | Returns an Astro `APIRoute`. |

Body parsing runs only for `POST`, `PUT`, and `PATCH`. In `auto` mode, the request `Content-Type` selects the parser.

Middleware stops unless it calls `next()`. A handler must write or end the response before the Astro route can complete.

## Errors

`ExpressError` represents response lifecycle and header errors. `ExpressBodyError` extends it for body parsing failures.

Multipart parser failures are recorded on `req.error`. Other uncaught errors return their message using `error.status` when present, otherwise status 500.

## Handle an application error

```ts title="src/pages/api/double.ts"
import { ExpressRoute } from '@astro-utils/express-endpoints';

const router = new ExpressRoute();

export const GET = router.route((req, res) => {
    const value = Number(req.query.value);
    if (req.query.value == null || !Number.isFinite(value)) {
        res.status(400).json({ error: 'Supply a numeric value query parameter.' });
        return;
    }
    res.json({ result: value * 2 });
});
```

Call `/api/double?value=4` for `{"result":8}`, or omit `value` to see the explicit JSON error. Catch application failures where you can turn them into a useful response. Do not expose internal exception details to callers. `ExpressError.code` is not the same property as the router’s `error.status` fallback; explicitly set the response status when handling an error.

---

# Advanced responses

Return a custom response from a nested Forms operation.

Source: https://withastro-utils.github.io/docs/reference/forms/advanced-responses/

## Stop processing and return a response

This is an Astro frontmatter excerpt for a page using the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md). A nested operation throws to stop page processing immediately:

```astro title="src/pages/account.astro"
---
import { ThrowOverrideResponse } from '@astro-utils/forms/forms.js';

function requireUser() {
    if (!Astro.locals.session.userId) {
        throw new ThrowOverrideResponse(Astro.redirect('/login'));
    }
}
requireUser();
---
```

Your authentication system must set `session.userId` after verifying the user. This guard is not an authentication implementation.

## Return a custom body

```astro title="src/pages/export.astro"
---
import { ThrowOverrideResponse } from '@astro-utils/forms/forms.js';

throw new ThrowOverrideResponse(new Response('name\nAlex\n', {
    headers: { 'Content-Type': 'text/csv; charset=utf-8' }
}));
---
```

## Constructor behavior

| Argument | Behavior |
| --- | --- |
| `response` | Optional native `Response` (or `null`). |
| `message` | Optional fallback message. |

If no response is supplied, Forms uses `Astro.locals.forms.overrideResponse`. If that is also missing, the fallback message is returned with status 500. The default message is `An error occurred, please try again later.`

For an ordinary redirect from a button callback, use the [redirect helper](https://withastro-utils.github.io/docs/guides/forms/js-helpers/index.md).

---

# Basic Form Components

Bound inputs, select controls, buttons, and validation feedback.

Source: https://withastro-utils.github.io/docs/reference/forms/basic-form-components/

The template excerpts below belong inside a `BindForm` using the [shared Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md). Import the components you use from `@astro-utils/forms/forms.js`.

## Inputs
### BInput

The basic component for most form fields.

```astro
<label for="meetingDate">Meeting date</label>
<BInput id="meetingDate" type="date" name="meetingDate" min="2026-01-01" max="2026-12-31" required/>
```

It includes the following attributes:

- **type** - HTML input types: `text`, `checkbox`, `date`, `email`, `number`, `radio`, `file`... / `int`
- **min** - number / date
- **max** - number / date
- **minlength** - minimum text length
- **maxlength** - maximum text length
- **pattern** - regex pattern for text
- **multiple** - for files
- **required** - a value must be provided
- **readonly** - make the value unchangeable
- **value** - default value, mainly use for the `readonly` attribute
- **as** - change the base element (default `input`, can be a React component)
- **parseTimeFormat** - for type `time` only, allowing you to parse and stringify time as milliseconds instead of a `Date`
- **props** - props for the `as` element

### BTextarea

Text-only input rendered as a `<textarea>` by default.

```astro
<label for="moreInfo">More information</label>
<BTextarea id="moreInfo" name="moreInfo" maxlength={400} required/>
```

It includes the following attributes:

- **minlength** - minimum text length
- **maxlength** - maximum text length
- **pattern** - regex pattern for text
- **required** - a value must be provided
- **readonly** - make the value unchangeable
- **as** - change the base element (default `textarea`, can be a React component)
- **props** - props for the `as` element

### BSelect

The select component lets the user choose one or more values.

```astro
<label for="favoriteFood">Favorite food</label>

<BSelect id="favoriteFood" name="favoriteFood" required={false}>
    <BOption disabled selected>Choose a food</BOption> <!-- The default, but not selectable -->
    <BOption>Pizza</BOption>
    <BOption>Salad</BOption>
    <BOption>Lasagna</BOption>
</BSelect>
```

- **type** - `text` / `date` / `number` - for parsing purposes
- **multiple** - select more than one value
- **required** - something must be selected (default `true`)
- **as** - change the base element (default `select`, can be a React component)
- **props** - props for the `as` element

#### BOption

The select option

- **value** - value to send to the server
- **disabled** - you cannot select this option

## Buttons
`BButton` is the general form control. You can also use it without `Bind` data.

```astro title="src/pages/basic-form-components.astro"
---
import { BButton, BindForm } from '@astro-utils/forms/forms.js';
import Layout from '../layouts/Layout.astro';

function sayHi(){
    console.log('Hi');
}
---
<Layout>
    <BindForm>
        <BButton onClick={sayHi}>Say hello</BButton>
    </BindForm>
</Layout>
```

Attributes:
- **onClick** - function to execute when the button is clicked
- **whenFormOK** - execute the function only if there isn't any error in the form
- **as** - change the base element (default `button`, can be a React component)
- **props** - props for the `as` element
- **state**: any - store state per button (must be used with `BindForm`)
- **extra**: any - store extra data per button (cannot be changed in the `onClick` function)

## Validation feedback

Show the form errors, so you can fix them and resubmit.

Most form validation is handled by the browser and repeated on the server. Add `errorMessage` when a field needs a clearer application-specific message.

```astro
<FormErrors title="Form errors"/>

<label for="number">Number</label>
<BInput id="number" type="int" min="1" name="number" errorMessage="Number must be at least 1"/>
```

Attributes:
- **title** - the error title

This will output the following if it got to the server validation:
```html title="HTML output"
<h4>Form errors</h4>
<ol>
    <li>Number must be at least 1</li>
</ol>
```

---

# Forms configuration

Middleware settings for sessions, large uploads, secrets, and logging.

Source: https://withastro-utils.github.io/docs/reference/forms/configuration/

After completing the [Forms setup](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md), pass settings to the middleware export in this file:

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms({
    secret: import.meta.env.FORMS_SECRET,
    session: {
        cookieName: 'session',
        cookieOptions: { httpOnly: true, sameSite: 'lax', secure: import.meta.env.PROD }
    },
    forms: {
        bigFilesUpload: {
            bigFileServerOptions: { maxUploadSize: 250 * 1024 * 1024 }
        }
    }
});
```

| Setting | Purpose |
| --- | --- |
| `secret` | Stable secret used by protected form state. Set this in production. |
| `session.cookieName` | Session cookie name. Default: `session`. |
| `session.cookieOptions` | Cookie serialization options. Defaults include HTTP-only, same-site lax, path `/`, and an age limit. |
| `forms.bigFilesUpload.bigFileClientOptions` | Chunk size, parallelism, retries, and retry delays. |
| `forms.bigFilesUpload.bigFileServerOptions` | Upload policy, size, duration, directory, and completion callback. |
| `logs(type, message)` | Receives middleware log events. |

Keep secrets outside source control. Set `secure: import.meta.env.PROD` for HTTPS production cookies and enforce upload policy before accepting untrusted files.

## Development and deployment

Before using the configuration above, set `FORMS_SECRET` in your environment (or an untracked local `.env` file). Generate a random value with `node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"`. Copy that value into the environment variable; never commit it. For an initial local experiment without custom settings, use `forms()` as shown in Getting Started.

Use a stable environment secret for deployed projects. `import.meta.env.PROD` enables secure cookies in the HTTPS production configuration while allowing local HTTP development. The middleware initializes request state; pages still need the integration and one `WebForms` root.

---

# Data binding API

Bind defaults, persisted state, validation results, and lifecycle hooks.

Source: https://withastro-utils.github.io/docs/reference/forms/data-binding/

For a complete walkthrough, start with [Binding & Validation](https://withastro-utils.github.io/docs/guides/forms/data-binding/index.md). The snippets here describe individual contracts; Astro frontmatter examples run inside a page using the [shared layout](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md#4-add-the-shared-layout).

## Create a bind

```astro title="src/pages/profile.astro"
---
import { Bind } from '@astro-utils/forms/forms.js';

type Form = { 
    name: string; 
    age: number 
};
const bind = Bind<Form>({ name: 'Unknown', age: 18 });
---
```

Defaults are optional. If you supply a typed defaults object, provide all required fields in that type. Inputs with matching `name` attributes read and update those properties on submission.

## Bind members

| Member | Purpose |
| --- | --- |
| Application fields | Values read and written by named controls. |
| `errors` | Validation errors, including the field name, submitted value, issues, and message. |
| `defaults()` | Reassigns the initial defaults. |
| `on.newState` | Runs when no previous view state was restored. |
| `on.stateLoaded` | Runs after state has been loaded. |
| `on.reloadState` | Refreshes parent data when a child requests a rerender. |

## Persist selected state

```astro title="src/pages/profile.astro"
<BindForm {bind} omitState={['message']}>
    <slot />
</BindForm>
```

`omitState` excludes fields from the next persisted view state. Use it for transient messages; keep passwords out of persisted state. Request-local variables are another way to display feedback for only the current response.

## Custom validation

```astro title="src/pages/profile.astro"
---
function validateName(value: string) {
    if (value.trim().toLowerCase() === 'admin') {
        return { code: 'reserved_name', error: 'This name is reserved.' };
    }
}
---
```

Pass the function as `validate={validateName}` on a bound input. It may return a promise. Return nothing to accept, `{ error, code? }` to reject, or `{ value }` to replace the parsed value. The current implementation applies a replacement only when it is truthy; use another approach for replacements such as `0`, `false`, or an empty string. A Zod schema is also accepted.

`FormErrors` displays the errors. Put `whenFormOK` on actions that must only run after successful validation.

## State values

View state supports SuperJSON values such as dates, maps, and sets in addition to ordinary serializable data. Do not store functions, live connections, or large datasets in it. Use [sessions](https://withastro-utils.github.io/docs/reference/forms/session/index.md) for small cross-page values and application storage for durable data.

---

# Client-side events & triggers

Observe submission and choose which bound button handles a browser event.

Source: https://withastro-utils.github.io/docs/reference/forms/events-and-triggers/

## Show submission feedback

```ts

document.addEventListener('WFSubmitting', (event) => {
    const { button } = (event as CustomEvent<{ button: HTMLButtonElement }>).detail;

    console.log(button.name, 'submitted!')
});

```

`WFSubmitting` reports the start of a form submission, but it does not guarantee completion. For stalled or failed uploads, provide explicit error or retry feedback; do not invent a completion event.

## Submit from a select

To submit a form from another browser event, use the global `submitForm` function.

```astro title="src/pages/events-and-triggers.astro"
---
import { Bind, BButton, BindForm, BSelect, BOption } from '@astro-utils/forms/forms.js';

type SelectForm = {
    select: string;
};

const bind = Bind<SelectForm>();

function onSubmit(){
    console.log(bind.select);
}
---
<BindForm {bind}>
    <label for="select">Selection</label>
    <BSelect id="select" name="select" required onchange="submitForm(this)">
        <BOption value="1">Option 1</BOption>
        <BOption value="2">Option 2</BOption>
    </BSelect>

    <BButton onClick={onSubmit} hidden>This button is hidden</BButton>
</BindForm>
```

### Choose the action
It will try to select the best BButton in this BindForm.

The order of selection is:
1. The last BButton with the `whenFormOK` attribute.
2. Last BButton in the form.

You can also manually configure that by adding the `onSubmitClick` attribute to the select.

```astro title="src/pages/events-and-triggers.astro"
<BSelect name="select" required onchange="submitForm(this)" onSubmitClick="consoleItButton">
    <BOption value="1">Option 1</BOption>
    <BOption value="2">Option 2</BOption>
</BSelect>

<BButton id="consoleItButton" onClick={onSubmit} hidden>This button is hidden</BButton>
```

### Submit a search on Enter

Here's another example using a search input that triggers form submission:

```astro title="src/pages/events-and-triggers.astro"
---
import { Bind, BButton, BindForm, BInput } from '@astro-utils/forms/forms.js';

type SearchForm = {
    searchQuery: string;
};

const bind = Bind<SearchForm>();

function onSearch(){
    console.log('Searching for:', bind.searchQuery);
}
---
<BindForm {bind}>
    <label for="searchQuery">Search</label>
    <BInput id="searchQuery" name="searchQuery" placeholder="Enter search term..." onSubmitClick="searchButton" />
    <BButton id="searchButton" onClick={onSearch}>Search</BButton>

    <BButton onClick={() => {}} whenFormOK>No Search</BButton>
</BindForm>
```

This example shows how to:
- Use a search input that submits on Enter key press
- Without `onSubmitClick`, submission defaults to the last button with `whenFormOK`.

### Update state without an action

When you only want to update the form state - reload the form without the need to click on a submit button.

```astro
<label>
    <BInput type="checkbox" name="showContent" onchange="submitForm(this)" onSubmitClick="state"/> Show content
</label>

{bind.showContent ? 'Content is shown' : 'Content is hidden'}
```

### WebForms Options

```astro
<WebForms loadingClassName="button-loading" preservePageScroll>
    <BindForm>
        ...
        <BButton onClick={...}>Submit</BButton> <!-- class name will be added on submission -->
    </BindForm>
</WebForms>
```

`preservePageScroll` - default true, will ensure the page will be scrolled to the exact same potions after form submission.

`loadingClassName` - the class name that will be added to the button being submitted to indicate a loading state.

---

# Forms imports

Choose the right Astro Utils Forms entrypoint for middleware, components, and Astro configuration.

Source: https://withastro-utils.github.io/docs/reference/forms/

Most application code imports from `@astro-utils/forms/forms.js`. The other entrypoints are used once during project setup.

## Build forms with `forms.js`

This is the main API for Astro pages and components. The page below assumes the [shared layout, middleware, and integration](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md) are installed:

```astro title="src/pages/index.astro"
---
import { Bind, BindForm, BButton, BInput, FormErrors } from '@astro-utils/forms/forms.js';

import Layout from '../layouts/Layout.astro';

type AccountForm = {
	email: string;
};

const bind = Bind<AccountForm>();

async function createAccount() {
	console.log(bind.email);
}
---

<Layout>
	<span slot="title">Account form</span>

	<BindForm {bind}>
		<FormErrors />

		<label for="email">Email</label>
		<BInput id="email" name="email" type="email" required />

		<BButton onClick={createAccount} whenFormOK>Create account</BButton>
	</BindForm>
</Layout>
```

It exports:

- Form structure: `WebForms`, `BindForm`, and `FormErrors`
- Controls: `BInput`, `BTextarea`, `BSelect`, `BOption`, and `BButton`
- State: `Bind` and the `BindTypes` type
- Large uploads: `UploadBigFile`, `UploadBigFileProgress`, `BigFile`, and `processBigFileUpload`
- Response control: `ThrowOverrideResponse`

Continue with [basic components](./basic-form-components/), [data binding](./data-binding/), [events](./events-and-triggers/), or [large uploads](./upload-big-file/).

## Add WebForms To Layout

Use one `WebForms` root around your form content.

```astro title="src/layouts/Layout.astro"
---
import { WebForms } from '@astro-utils/forms/forms.js';
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width" />
        <title><slot name="title" /></title>
    </head>
    <body>
        <WebForms>
            <slot />
        </WebForms>
    </body>
</html>
```

## Add the middleware

The package root exports the Forms middleware as its default export. Add it to `src/middleware.ts`:

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';

export const onRequest = forms();
```

The middleware prepares form state, sessions, validation, and response handling for each request. See [configuration](./configuration/) for its options.

## Add the Astro integration

The integration entrypoint exports the Astro integration as its default export. Add it once in `astro.config.mjs`:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import forms from '@astro-utils/forms/dist/integration.js';

export default defineConfig({
	integrations: [forms]
});
```

Start with the complete [installation and first form guide](https://withastro-utils.github.io/docs/guides/forms/getting-started/index.md).

---

# Session

Configure a signed session cookie and share small values between Forms pages.

Source: https://withastro-utils.github.io/docs/reference/forms/session/

Astro Utils Forms uses a session to store [CSRF](https://developer.mozilla.org/en-US/docs/Glossary/CSRF) validation secrets and application values.

The session is stored as an signed JSON Web Token in a browser cookie.

## Read and update session values

Access the session through `Astro.locals` inside a page wrapped by `WebForms`.

```astro title="src/pages/session.astro"
---
import { BindForm, BButton } from "@astro-utils/forms/forms.js";
const { session } = Astro.locals;
session.counter ??= 0;

function increase() {
  session.counter++;
}
---
<BindForm>
    <p>Current counter: {session.counter}</p>
    <BButton onClick={increase}>++</BButton>
</BindForm>
```

### Configuration

All the configuration is in the middleware creation.

```ts title="src/middleware.ts"
import astroFormsMiddleware from '@astro-utils/forms';
import {sequence} from 'astro/middleware';

export const onRequest = sequence(
    astroFormsMiddleware({
        secret: import.meta.env.FORMS_SECRET,
        session: {
            cookieName: 'session',
            cookieOptions: {
                httpOnly: true,
                sameSite: 'lax',
                secure: import.meta.env.PROD,
                maxAge: 60 * 60 * 24 * 7,
            },
        },
    })
);
```

## Lifetime and contents

`maxAge` is measured in seconds; the example lasts seven days. Keep `FORMS_SECRET` stable across restarts. An expired or invalid token starts an empty session; changing the signing secret invalidates existing sessions.

A signature detects tampering; it does **not** hide the payload from the cookie holder. Store small identifiers and preferences, not passwords or confidential records. Cookies have a limited size and accompany requests, so move growing lists and durable data into application storage. Set `secure` for HTTPS deployments; local HTTP development needs it disabled.

---

# Large file upload API

Configure chunked uploads, match progress controls, and handle failures.

Source: https://withastro-utils.github.io/docs/reference/forms/upload-big-file/

## Upload a file

The big file upload component is a simple way to upload large files to the server. It uses the `xhr` API to upload the file in chunks (and not all at once). This way, the server can handle large files without running out of memory.

It is also able to show the progress of the upload and handle errors (in the server side).

## Components

### UploadBigFile

Same as the `BInput` component, but for big files.

```astro title="src/pages/upload-big-file.astro"
---
import { type BigFile, BButton, Bind, BindForm, FormErrors, UploadBigFile, UploadBigFileProgress } from '@astro-utils/forms/forms.js';

import Layout from '../layouts/Layout.astro';

type Form = {
    file: BigFile;
}

const bind = Bind<Form>();
let showSubmitText = '';

function submit(){
    showSubmitText = `You uploaded ${bind.file.name} (${bind.file.size} bytes)`;
}
---
<Layout>
<span slot="title">Upload a file</span>
<BindForm {bind}>
    <FormErrors />
    <p>{showSubmitText}</p>

    <label for="file">File</label>
    <UploadBigFile id="file" name="file" required/>

    <BButton onClick={submit} whenFormOK>Submit</BButton>
</BindForm>
</Layout>
```

### UploadBigFileProgress

A progress bar connected to an `UploadBigFile` component.

```astro title="src/pages/upload-big-file.astro"
<UploadBigFile name="file" required/>
<UploadBigFileProgress for="file" />
```

## Configure upload limits

Pass limits through your Forms middleware. This is a configuration example, not a type declaration:

```ts title="src/middleware.ts"
import forms from '@astro-utils/forms';
export const onRequest = forms({
    secret: import.meta.env.FORMS_SECRET,
    forms: {
        bigFilesUpload: {
            bigFileClientOptions: { chunkSize: 5 * 1024 * 1024, parallelChunks: 2, retryChunks: 3 },
            bigFileServerOptions: { maxUploadSize: 20 * 1024 * 1024, maxUploadTime: 5 * 60 * 1000 }
        }
    }
});
```

Sizes are bytes and `maxUploadTime` is milliseconds. The example caps a file at 20 MiB and configures five minutes as the age limit used when cleaning temporary uploads; this is not a guaranteed transfer timeout. Choose limits and a temporary directory that fit your deployment.

## Match the progress control

`for="file"` targets the upload control's `name="file"`, not its HTML `id`. Keep this pairing consistent when adding a custom ID for a label.

## Explain failures to the user

An interrupted or rejected upload may never reach the button callback. Do not report success until that callback completes. In your application, show the failure near the input and let the user retry; `FormErrors` handles form validation, not every transport failure.

The [upload example](https://withastro-utils.github.io/docs/examples/upload/index.md) provides a simulated failure mode so you can compare success and retry feedback without transferring a file. For server processing failures inside your callback, catch the error and render a request-local message without exposing internal paths or exception details.