Query Reference
@svelte-lean/query/forms
Server errors into native form state: an attachment that writes aria-invalid, aria-describedby, custom validity and focus, and removes exactly what it wrote.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Import
import { fieldErrors, issues, errorKey } from '@svelte-lean/query/forms';Usage
<script lang="ts">
import { createMutation } from '@svelte-lean/query';
import { fieldErrors, issues } from '@svelte-lean/query/forms';
import { createMember } from '$api/members';
const save = createMutation(createMember);
function submit(event: SubmitEvent & { currentTarget: HTMLFormElement }) {
event.preventDefault();
const data = new FormData(event.currentTarget);
save.run({
name: String(data.get('name')),
email: String(data.get('email')),
team: 'Design',
role: 'member'
});
}
</script>
<!-- The server's 422 marks the fields: aria-invalid, aria-describedby, custom validity, focus. -->
<form {@attach fieldErrors(() => save.error)} onsubmit={submit}>
<label>Name <input name="name" required /></label>
{#each issues(save.error, 'name') as message (message)}<p>{message}</p>{/each}
<label>Email <input name="email" type="email" required /></label>
{#each issues(save.error, 'email') as message (message)}<p>{message}</p>{/each}
<button disabled={save.busy}>Invite</button>
</form>Size
Production Vite builds of a small consumer entry, Svelte external. A marginal row is the bytes the entry adds over the row it names.
| Build | Over | gzip | brotli | Budget (gzip) |
|---|---|---|---|---|
forms (marginal) | query+mutation | 1406 B | 1226 B | 1600 B |
Read from packages/query/artifacts/size.json. Every entry and its method: Performance.
Functions
The attachment and two readers of an error.
Exports
Runtime exports of the entry.
| Name | Type | Default | Description |
|---|---|---|---|
# fieldErrors | (source: () => QueryError | FailureResult | undefined, options?: FieldErrorsOptions) => FormAttachment | – | {@attach fieldErrors(() => save.error)} on a form: marks the controls the error names; re-runs when the error changes. |
# issues | (source, path?: string) => FieldIssue[] | string[] | – | Every issue, or the messages of one path (the exact key, then its wildcard form 'lines.*.sku'). |
# errorKey | (error: QueryError) => ErrorKey | – | A stable, untranslated key for i18n. |
Options
FieldErrorsOptions, the second argument of fieldErrors().
FieldErrorsOptions
All optional.
| Name | Type | Default | Description |
|---|---|---|---|
# name | (path: string) => string | the dot path, the bracket form, then name[] | Server path to control name. |
# focus | boolean | true | Focus the first invalid control; never taken from a control being typed in. |
# validity | boolean | true | setCustomValidity(first message) on each marked control. |
# text | (message, path) => string | identity | Translate a field message. |
# unmatched | (issues: FieldIssue[]) => void | – | Issues with no control in this form, to render elsewhere. |
FieldIssue
One message of issues().
ErrorKey
What errorKey() returns: the kind, with HTTP statuses split.
| Name | Type | Default | Description |
|---|---|---|---|
# network | ErrorKey | – | No answer. |
# timeout | ErrorKey | – | The attempt timed out. |
# server | ErrorKey | – | HTTP 5xx. |
# rate-limited | ErrorKey | – | HTTP 429. |
# not-found | ErrorKey | – | HTTP 404. |
# conflict | ErrorKey | – | HTTP 409. |
# http | ErrorKey | – | Any other HTTP status. |
# forbidden | ErrorKey | – | 401 or 403, or a refusal classified as forbidden. |
# validation | ErrorKey | – | A 422 or a refusal with field errors. |
# refused | ErrorKey | – | An application refusal (success: false). |
# parse | ErrorKey | – | The answer did not match its schema. |
Guide
How to use it, with examples: Forms. All entry points: Svelte Lean Query.