Forms app
This page covers what Forms adds to the Vue side of your app: its pages, components, composables and utils. It is for app developers. Set up the module first: Overview.
Pages
Each page, its default path and its custom path are set by its option. The admin paths follow the base path of Admin.
Components
| Component | Props | Notes |
|---|---|---|
<FormRenderer> | slug?, form?, password?, preview?, locale? | Renders a published form by slug, or a given definition. Emits submitted(id) and previewed(answers). |
<FormEmbed> | slug, title?, locale?, class? | Embeds a published form and follows its access settings. |
<FormPreview> | slug, name?, definition?, contentKey? | The admin preview. |
<FormSubmissionView> | submission | Renders a submission against the definition it was answered with. |
Embed a form in Markdown
FormEmbed is registered globally, so Nuxt Content resolves it in any collection. Use the
block syntax: the embed renders block elements, and the inline :form-embed{...} would put them inside a paragraph.
::form-embed{slug="contact"}
::
::form-embed{slug="contact" title locale="da" class="max-w-2xl my-8"}
::
| Prop | Type | Default | Purpose |
|---|---|---|---|
slug | string | none | Required. The slug of a published form. |
title | boolean | false | Shows the form's name as a heading. |
locale | string | the app locale | Overrides the locale of the form's texts. |
class | string | none | Extra classes for the wrapper, which has not-prose. |
The embed asks GET /api/forms/:slug/access what to render:
| Form state | Renders |
|---|---|
| Open | The form, with a loading skeleton. The renderer handles the success message or redirect. |
| Unknown or unpublished | A "could not be found" alert. |
auth: 'user' | A sign-in prompt that links to the login page and back. |
auth: 'password' | The password gate. |
availability: 'api' or auth: 'token' | Nothing. In development, a console warning names the slug. |
Composables
All composables are auto-imported. @frigear-nu/forms/composables exports them too.
useForm(slug: MaybeRefOrGetter<string>, password?: MaybeRefOrGetter<string | undefined>) // published definition
useFormAccess(slug: MaybeRefOrGetter<string>) // FormAccessInfoDto: access, signedIn, open, opensAt
useFormsLocale() / useFormsLocales() // current locale / available locales
useFormsPaths() // (name, params?) => resolved page path
useFormLink() // { enabled, url(slug), copy(slug) }
useFormStepper(...) // step navigation of the renderer
useFormActions() // { busy, create, clone, remove, importJson, redeliver, menu, submissionMenu }
FORM_PASSWORD_HEADER // 'x-form-password'
useFormActions() gives your own pages the staff actions of the admin list.
menu(form, { open?, extra?, onRemoved? })builds the row menu: Open, Submissions, Copy link and Duplicate form, then Archive form in its own group.open: falseleaves out Open, andextraitems follow it.importJson()opens the import slideover. It resolvestruewhen forms were imported.submissionMenu({ id, formId }, { open?, onRedelivered? })offers Open and Deliver again.
Utils
@frigear-nu/forms/utils has no side effects, so it is safe in the Vue app and in Nitro.
| Export | Purpose |
|---|---|
defineForm, parseFormDefinition, formDefinitionSchema | Write and validate definitions. |
buildFormSchema, buildFieldSchema, validatedFields | Compile a definition into a zod schema. |
evaluateCondition, resolveVisibility, isFieldVisible | Conditional visibility. |
resolveAccess, defaultAccess, accessSchema | The effective access of a definition. |
isFormOpen, nextFormOpening | The open period. |
composeEmail, renderTemplateText, renderTemplateHtml, unknownBodyVariables, availableVariables | Email rendering. |
composePhone, parsePhone, phoneCountries, allPhoneCountries | Phone numbers. |
resolveEmailDelivery, resolveCaptcha, renderMarkdown | Delivery recipients, the captcha provider and static Markdown. |
formsApi | Typed paths of the routes, also in @frigear-nu/forms/api. |
The builder helpers, such as moveField, insertField and setAccess, come from the same path.
Next steps
- Definition – what the renderer shows: fields, steps and conditions.
- Server API – the access modes the embed follows.
- Reference – the routes behind these composables.