feat: label position (top, bottom, before, after) for fields by kevinchappell · Pull Request #525 · Draggable/formeo

kevinchappell · 2026-10-01T12:54:47Z

Summary

New config.labelPosition: top, bottom, before or after. before/after put the label beside the control (mirrored in RTL) and stack when the column is narrow. DOM order always matches what you see.
The Configuration panel offers it as a Label Position dropdown. Config declarations can now have options, which makes the item a dropdown. Adding Label Position from "Add config" starts at the position the field already shows.
Rendered fields with a visible label get a stable wrapper class: f-field f-label-<position>.
Checkbox and radio groups are named by their label (role="group" + aria-labelledby). Before this, the group label's for pointed at a <div>.
New CSS custom property --formeo-label-width (10rem).
Translations for the new keys: Draggable/formeo-languages branch feat/label-position-keys. Until that ships, the panel falls back to "Label Position" and "Top"/"Bottom"/"Before"/"After".

Compatibility

config.labelAfter still renders the same (true is bottom, or after for a lone checkbox/radio). The editor converts it to labelPosition on load, so forms save with labelPosition.
Group labels lose for="f-<id>" and gain id="f-<id>-label". Update any selector like label[for="f-<groupId>"].
Stacked labels are display: block. A labelled field's wrapper had class=""; it now has f-field f-label-<position>.
In the editor, while a field is being edited, a bottom/after label shows above the edit window instead of below it.
Editor configs that disabled or relabelled labelAfter (for example disabled: ['config.labelAfter'] or panels.config.options.labelAfter) no longer have any effect. Switch those keys to labelPosition.

Test plan

npm test (890 passing), npm run test:types, npm run lint, npm run build:lib
Playwright: tests/label-position.spec.js (each position in editor and renderer, narrow, RTL, long label, condition-hidden before/after fields, label click focus, group names) plus the full suite (206 passed, 3 skipped)
dist/formData_schema.json diff is only labelPosition/labelAfter

Fixes #243

Please squash-merge.

…elAfter Refs #243

…apper Refs #243

…e=group Refs #243

… declaration Refs #243

…belAfter on load Refs #243

Refs #243

…osition order Refs #243

…ack them when narrow Refs #243

Refs #243

…ties suite Refs #243

Refs #243

… container Refs #243

…ition Refs #243

…kbox never stacks Refs #243

Refs #243

Copilot

Copilot review overview

🟡 Changes recommended

The generic configuration API mishandles non-field labelPosition keys and its TypeScript contract permits declarations rejected at runtime.

Review effort: Balanced
Findings: 1

Open (1)

Restrict labelPosition special handling to fields · New

What changed in this PR

Adds configurable field-label positioning across the editor, renderer, styling, schema, types, accessibility, and documentation.

Changes:

Supports top, bottom, before, and after label positions with legacy labelAfter migration.
Adds dropdown-based configuration declarations and responsive/RTL styling.
Improves checkbox/radio group labelling and expands automated coverage.

File	Description
`tools/formdata-schema.mjs`	Adds label-position schema fields.
`tests/label-position.spec.js`	Adds end-to-end position and accessibility tests.
`tests/add-configuration.spec.js`	Updates configuration-panel tests.
`src/types/formeo.test-d.ts`	Tests new public types.
`src/types/formeo.d.ts`	Defines label positions and dropdown declarations.
`src/lib/sass/css-properties.test.mjs`	Tests label-width and layout CSS.
`src/lib/sass/components/_group-actions.scss`	Updates hover styling for wrappers.
`src/lib/sass/base/_properties.scss`	Adds the label-width custom property.
`src/lib/sass/base/_bs.scss`	Implements responsive label layouts.
`src/lib/sass/__fixtures__/formeo-baseline.css`	Updates compiled CSS fixture.
`src/lib/js/renderer/option-groups.test.js`	Updates group-label assertion.
`src/lib/js/renderer/label-position.test.js`	Tests renderer positioning and groups.
`src/lib/js/renderer/index.js`	Adds wrapper position classes.
`src/lib/js/formdata-schema.test.mjs`	Tests schema validation.
`src/lib/js/components/fields/index.js`	Declares the position dropdown.
`src/lib/js/components/fields/field.js`	Normalizes and renders editor labels.
`src/lib/js/components/fields/field-label-position.test.js`	Tests editor migration and wrappers.
`src/lib/js/components/edit-panel/edit-panel.test.js`	Tests dropdown declarations and defaults.
`src/lib/js/components/edit-panel/edit-panel.js`	Initializes added label positions.
`src/lib/js/components/edit-panel/edit-panel-item.mjs`	Renders declared options as selects.
`src/lib/js/components/edit-panel/config-options.test.mjs`	Tests dropdown declaration validation.
`src/lib/js/components/edit-panel/config-options.mjs`	Validates and labels dropdown choices.
`src/lib/js/components/controls/control-config-options.test.js`	Updates default field options.
`src/lib/js/common/label-position.test.mjs`	Tests position resolution and migration.
`src/lib/js/common/label-position.mjs`	Centralizes label-position logic.
`src/lib/js/common/dom.test.js`	Tests label DOM ordering.
`src/lib/js/common/dom.js`	Adds group ARIA naming and ordering.
`README.md`	Documents label-width theming.
`docs/renderer/renderer.md`	Documents renderer behavior and compatibility.
`docs/options/controls/README.md`	Documents control dropdown declarations.
`docs/options/config/README.md`	Documents configuration options.
`docs/css-frameworks.md`	Documents field wrapper classes.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

kevinchappell · 2026-10-01T13:04:29Z

    const newConfig = new EditPanelItem({
      key: `config.${configKey}`,
-      data: declaration.default,
+      data: configKey === 'labelPosition' ? resolveLabelPosition(this.component.data) : declaration.default,


Good catch, fixed in d908c13. The resolved-position start now applies only when the component is a field. A stage, row or column that declares its own labelPosition option keeps its declared default. Covered by a new test in edit-panel.test.js.

… position A stage, row or column that declares its own labelPosition config option keeps its declared default when it's added from the dialog. Those components have no field label to resolve. Refs #243

# [5.16.0](v5.15.1...v5.16.0) (2026-10-01) ### Features * label position (top, bottom, before, after) for fields ([#525](#525)) ([30606cd](30606cd)), closes [#243](#243)

kevinchappell · 2026-10-01T14:35:58Z

🎉 This PR is included in version 5.16.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

kevinchappell added 18 commits October 1, 2026 12:22

feat(dom): resolve label position from labelPosition, then legacy lab…

19c3a13

…elAfter Refs #243

feat(renderer): give labelled fields an f-field f-label-<position> wr…

9dbcfc2

…apper Refs #243

fix(renderer): name checkbox and radio groups by their label with rol…

3682d3c

…e=group Refs #243

feat(editor): config panel dropdowns from an options list on a config…

e9af548

… declaration Refs #243

feat(editor): offer Label Position in the Config panel and convert la…

5f75b11

…belAfter on load Refs #243

fix(editor): keep each field method's docblock and test an empty config

ae517ae

Refs #243

feat(editor): wrap a field's label and preview in f-field, in label-p…

7a130f2

…osition order Refs #243

feat(styles): lay out before/after labels beside their control and st…

eeded7e

…ack them when narrow Refs #243

feat(types): labelPosition in the formData schema and type definitions

8f5e7fe

Refs #243

fix(types): export the label position fixtures and regroup LabelPosition

7acea3a

Refs #243

docs: label position, the f-field wrapper and --formeo-label-width

0788ec6

Refs #243

test(e2e): label positions in the editor and the rendered form

3cc941e

Refs #243

test(styles): move the label position CSS test into the custom proper…

51f05f6

…ties suite Refs #243

fix(styles): keep condition-hidden before/after fields hidden

d24c2bf

Refs #243

fix(dom): keep label wrapper classes off the group element and button…

796cf68

… container Refs #243

fix(editor): start an added Label Position at the field's current pos…

653606f

…ition Refs #243

docs: how Label position is added in the editor, and that a lone chec…

83672d4

…kbox never stacks Refs #243

docs(types): a ConfigOptionDeclaration with options is a dropdown

72084da

Refs #243

Copilot AI balanced review requested due to automatic review settings October 1, 2026 12:54

Copilot started reviewing on behalf of kevinchappell October 1, 2026 12:55 View session

Copilot AI reviewed Oct 1, 2026

View reviewed changes

fix(editor): start only a field's added Label Position at its current…

d908c13

… position A stage, row or column that declares its own labelPosition config option keeps its declared default when it's added from the dialog. Those components have no field label to resolve. Refs #243

kevinchappell merged commit 30606cd into main Oct 1, 2026
2 checks passed

kevinchappell deleted the feat/243-label-position branch October 1, 2026 13:25

kevinchappell added the released label Oct 1, 2026

Navigation Menu

feat: label position (top, bottom, before, after) for fields - #525

feat: label position (top, bottom, before, after) for fields#525
kevinchappell merged 19 commits into
mainfrom
feat/243-label-position

kevinchappell commented Oct 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

kevinchappell Oct 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

kevinchappell commented Oct 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kevinchappell commented Oct 1, 2026

Summary

Compatibility

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

kevinchappell Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kevinchappell commented Oct 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kevinchappell Oct 1, 2026 •

edited

Loading