GrFormSection — Components

Overview

When to take it

the form is long — “Contacts”, “Delivery”, “Payment”: the sections give structure and points of navigation;
the section is needed by a blind user — the heading renders as an h2…h6 tag, and the form is walked by headings;
the section has actions — “Add”, “Reset” in the right part of the header;
the section needs an explanation — a description under the heading rather than a hint at every field.

When to take something else

Need	Take
Rules and submission	`GrForm`
The wrapper of a single field	`GrFormField`
The sections are switched rather than following one another	`GrTabs`
The section collapses	`GrCollapse`
Just a card is needed	`GrCard`

Playground controls come from the API, not from hand

Stage

Loading…

0 changed· state is in the URL

vue

<GrFormSection title="Billing contact" description="Invoices and payment reminders go to these addresses."><div class="grid gap-3"><GrFormField label="Invoice email"><GrInput modelValue="[email protected]" type="email" /></GrFormField><GrFormField label="Copy to"><GrInput modelValue="[email protected]" type="email" /></GrFormField></div></GrFormSection>

Examples 3 each with a live demo and its code

A checkout read by its headings
A long form gets structure from its sections: each title is a real h3 under the page’s h2, so a screen reader walks the form by headings, and the description speaks for the group — «we send the receipt here» — rather than hanging on the first field.
Checkout
Contact
We send the receipt and delivery updates here.
Email
Phone
Delivery address
Couriers deliver on weekdays, 9:00–18:00.
Full name
Street
City
Eircode
Payment
Pay with
Visa ending 4242 Saved card, expires 08/28
Invoice Pay within 30 days by bank transfer
An action that belongs to the section
The title slot carries a counter next to the heading, and the actions slot holds what applies to the whole section — «Reset to defaults». Inside the list such a button would compete with the switches it resets.
Notifications 3 of 5 on
Email notifications for [email protected]
An invoice is paidRight away
An invoice becomes overdueThe morning after the due date
Weekly revenue summaryMondays at 9:00
Someone mentions youIn comments and notes
Product newsAbout once a month
Security as a landmark, and a danger zone
landmark turns a large section into a region named by its heading, worth it where people jump straight to «Security». The danger zone puts its one action in the head through actions and a link in the description slot.
Security
Applies to every member of the workspace.
Sign members out after
Danger zone
Deleting removes projects, invoices and members. What is kept for tax purposes

API generated from the package · cannot drift

Props

Prop	Type	default	Description
`title`	`string \| undefined`	`undefined`	The heading of the section — a real `h2`…`h6` by which the form is navigated. The `#title` slot is stronger.
`description`	`string \| undefined`	`undefined`	An explanation under the heading, linked to the section through `aria-describedby`. The `#description` slot is stronger.
`headingLevel`	`2 \| 3 \| 4 \| 5 \| 6 \| undefined`	`undefined`	The level of the heading to fit the structure of the page. Unset — it comes from `GrConfigProvider`, otherwise `3`.
`landmark`	`boolean \| undefined`	`false`	Declare the section a `region` landmark. Off by default: five sections of a form would give five landmarks and clutter the overview, while the structure is carried by the heading anyway. It is worth switching on where the section really is large and it is worth jumping to it as to a region.

Slots

Slot	Type	Description
`default`	`any`	The content of the section.
`title`	`any`	The heading as a whole — instead of the `title` string.
`description`	`any`	The description as a whole — instead of the `description` string.
`actions`	`any`	The actions in the right part of the header: "Add", "Reset".

Types

Every exported type of the subpath, grouped by the file it lives in. Names, generics and bodies come from the package’s declaration files and cannot drift.

Import

import type { GrFormSectionProps, GrFormSectionConfigurableProps, GrFormSectionHeadingLevel } from '@feugene/granularity/components/GrFormSection'

Filedist/types/components/GrFormSection/GrFormSection.vue.d.ts

GrFormSectionPropsinterface

interface GrFormSectionProps {
    title?: string;
    description?: string;
    headingLevel?: GrFormSectionHeadingLevel;
    landmark?: boolean;
}

Filedist/types/components/GrFormSection/config.d.ts

grFormSectionConfigconst

const grFormSectionConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrFormSection">;

Filedist/types/components/GrFormSection/defaults.d.ts

GrFormSectionConfigurablePropsinterface

interface GrFormSectionConfigurableProps {
    headingLevel: GrFormSectionHeadingLevel;
}

Filedist/types/components/GrFormSection/grFormSectionStyles.d.ts

GrFormSectionHeadingLeveltype

type GrFormSectionHeadingLevel = typeof GR_FORM_SECTION_HEADING_LEVELS[number];

Filedist/types/components/GrFormSection/safelist.d.ts

grFormSectionSafelistconst

const grFormSectionSafelist: string[];

Usage from the library prose

The heading is real

A blind user walks a long form by headings, so the heading of a section renders as an h2…h6 tag rather than as bold text:

vue

<GrFormSection title="Profile" :heading-level="2" description="Public data">
  <GrFormField label="Name"><GrInput v-model="name" /></GrFormField>
</GrFormSection>

headingLevel is 3 by default and is read from GrConfigProvider (componentDefaults.GrFormSection.headingLevel) — the level is set once for the whole application, if the form has a page structure of its own.

A landmark on request

The root is a <section>, but without a name: a named section becomes a region landmark, and five sections of a form would give five regions in the overview of a screen reader. The structure is carried by the heading.

Where a section really is large and it is worth jumping to it as to a region, switch landmark on — the name will come from the heading:

vue

<GrFormSection landmark title="Security" />

The description is linked to the section through aria-describedby in both modes.

The slots

Slot	What it replaces
`title`	the heading as a whole — a link, a badge, a counter
`description`	the description as a whole
`actions`	the right part of the header: “Add”, “Reset”
`default`	the content of the section

The header is a single row: the heading with the description on the left, the actions on the right; on a narrow screen the actions wrap under the heading. Without a heading, a description and actions the header is not rendered at all.

The border and collapsing

There are deliberately no bordered/collapsible props — that is composition, not a setting:

vue

<GrCard class="p-4">
  <GrFormSection title="Profile" />
</GrCard>

Collapsing is given by GrCollapse — it has the same headingLevel, so the structure of the headings does not break.

Overview

When to take it

When to take something else

Playground controls come from the API, not from hand

Examples 3 each with a live demo and its code

Checkout

Contact

Delivery address

Payment

Notifications 3 of 5 on

Security

Danger zone

API generated from the package · cannot drift

Props

Slots

Types

Usage from the library prose

Related the fourth question: when not this