Form Component Architecture for EDS 2.0 - FormControl vs Hook-based approach

[pomfrida]

Background

As part of our v2 component migration to vanilla CSS and custom CSS variables, I've been working on Checkbox 2.0 and noticed we have inconsistent error handling patterns across our form components:

• TextField/Textarea: Use variant="error" + helperText via InputWrapper
• Checkbox/Radio/Switch: No built-in error handling - users must manually add ARIA attributes and error messages

Since we're building .new components that live alongside v1 with deprecation warnings, we have the opportunity to design a consistent form pattern from the start without breaking changes.

// Current: Inconsistent patterns
<TextField 
  label="Email"
  variant="error"
  helperText="Invalid email"
/>

<Checkbox 
  label="Accept terms"
  // ❌ No error handling built-in
  // Users must manually add ARIA attributes
/>

Why Not Just Use InputWrapper?

We already have InputWrapper that handles labels, helper text, and errors for TextField/Textarea. Why not reuse it?
InputWrapper places labels above the input (vertical layout), but Checkbox/Radio/Switch need labels beside the input (inline layout).

Could we make InputWrapper.new flexible enough?
Yes, we could! We could add layout props like direction="vertical" | "inline" and make it work for both patterns.
But consider:

1. Complexity - One component trying to handle multiple layout patterns becomes more complex:
   • Conditional rendering logic for vertical vs inline layouts
   • More props to configure (labelPosition, inlineLabelAfter, etc.)
   • Harder to maintain and understand
2. Still missing group support - InputWrapper is designed for single inputs. For checkbox/radio groups, we'd need additional components anyway (Fieldset, group validation, etc.)

In summary: InputWrapper.new could work, but building focused components gives us a cleaner architecture with less complexity.

What About Duplicating the Current Pattern?

Another option: Keep the current pattern from TextField/Textarea - each component handles its own label, helper text, and error state internally.

Example:

// Each component has its own implementation
<Checkbox
  label="Accept terms"
  helperText="Required for signup"
  variant="error"
/>

<Radio
  label="Option A"
  helperText="This is the default"
  variant="error"
/>

Why this isn't ideal:

• Code duplication - Label, helper text, and error styling logic gets duplicated in Checkbox, Radio, Switch, and future form components
• Inconsistent behavior - Small differences inevitably creep in when the same logic exists in multiple places
• Harder to maintain - A bug fix or style tweak needs to be applied to 5+ components
• More testing burden - Each component needs its own full test suite for label/error/helper text behavior
• Larger bundle size - Same CSS and logic shipped multiple times

The Question

Should we build form wrapper components for our v2 component suite to provide consistent error handling, validation, and accessibility across all form inputs?

Research: Two Main Approaches

I've researched how other major design systems handle this:

Approach 1: FormControl Pattern

Used by: Material UI, Chakra UI, Ant Design

Uses a wrapper component with Context API to distribute state (error, disabled, required) to all children.

Example:

<FormControl error disabled required>
  <FormLabel>Email address</FormLabel>
  <Input />
  <FormHelperText>Error message here</FormHelperText>
</FormControl>

Pros:

• Context automatically distributes state to children
• Well-established pattern in the React ecosystem
• Works well with complex nested forms

Cons:

• More complex implementation (Context API)
• Slightly more components to maintain
• Context can have performance implications

Approach 2: Hook-based Pattern

Used by: designsystemet.no

Uses simple Field wrapper + hooks for group management. Native <fieldset> for semantics.

Example:

// Individual field
<Field>
  <Input type="checkbox" />
  <Label>Checkbox label</Label>
  <ValidationMessage>Error message</ValidationMessage>
</Field>

// For groups
const { getCheckboxProps, validationMessageProps } = useCheckboxGroup({
  error: 'Select at least 2',
  value: ['email'],
  onChange: (values) => setValues(values)
});

<Fieldset>
  <Fieldset.Legend>How to contact you?</Fieldset.Legend>
  <Checkbox label="Email" {...getCheckboxProps('email')} />
  <Checkbox label="Phone" {...getCheckboxProps('phone')} />
  <ValidationMessage {...validationMessageProps} />
</Fieldset>

Pros:

• Simpler implementation (no Context)
• Uses native HTML semantics (<fieldset>, <legend>)
• Hook pattern is modern and flexible
• Lower complexity, easier to maintain
• Already uses vanilla CSS (matches our migration)

Cons:

• Less common pattern (not as widely used as FormControl)
• Hooks can't be used conditionally (standard React limitation)

My Recommendation

Approach 2 (designsystemet.no style) for these reasons:

1. Simpler - Less complexity, easier to maintain
2. Semantic HTML - Uses native <fieldset> which is correct for form grouping
3. Modern React - Hook-based patterns are idiomatic
4. Tech stack alignment - Already uses vanilla CSS like we're migrating to
5. Proven - Working well in a Norwegian design system

Components Needed

For Approach 2, we'd need:

• Field - Simple wrapper for individual inputs
• Fieldset + Fieldset.Legend + Fieldset.Description - Grouping components
• ValidationMessage - Shared error/helper text component
• useCheckboxGroup - Hook for managing checkbox groups
• useRadioGroup - Hook for managing radio groups (future)

Benefits

• ✅ Zero breaking changes - v1 components remain untouched
• ✅ Consistent API - All v2 form components follow the same pattern
• ✅ Automatic ARIA - Reduces accessibility bugs
• ✅ DRY code - Helper text logic not duplicated across components
• ✅ Foundation for v2 - Works for Checkbox.new, Radio.new, Switch.new, TextField.new, etc.

Proposed Plan

If we agree on this approach:

1. Pause Checkbox 2.0 briefly
2. Build the form foundation (Field, Fieldset, ValidationMessage, hooks)
3. Integrate Checkbox.new with the new foundation
4. Ship a complete, cohesive solution

This way we deliver a consistent form system from day one of v2, rather than retrofitting later.

Questions for Discussion

1. Which approach do you prefer - FormControl (Approach 1) or Hook-based (Approach 2)?
2. Any other patterns or approaches we should consider?

Looking forward to hearing your thoughts! 💭

[torleifhalseth]

Great discussion @pomfrida 🔥

I would focus on creating pure form components without state or context. Make it as simple and close to native form elements as possible with the necessary elements to achieve the style we want.

I would also recommend having a look at other headless design system libraries like Base UI and Radix UI:
https://base-ui.com/react/components/field
https://www.radix-ui.com/themes/docs/components/text-field

Less is more ✨

We could create stories where we use libraries like react-hook-form for state as proof of concept https://react-hook-form.com/.

[millus]

Very nice presentation of the different approaches, and I agree that its smart to have a solution on this from the beginning to avoid going back and fix new components. I like the simpler approach, especially using semantic html and vanilla css, i think it will be easier to maintain and work on! Also considering what Victor mentioned in one of our meetings regarding that the newer form elements will be easier to style as native form controls using modern css, so lets keep it close to native where we can, so yay to fieldset and legend 👍

[pomfrida]

Thanks both, this is super helpful 🙌
Great to see alignment around keeping things close to native form controls and avoiding unnecessary complexity.

Based on this, I'll start planning work on:
• Build a minimal Field + Fieldset foundation using semantic HTML (fieldset, legend, input, label)
• Add a shared ValidationMessage component
• Introduce hook-based group logic (useCheckboxGroup, useRadioGroup)
• Keep the components headless and stateless (no internal form state, no context)
• Ensure styling stays pure vanilla CSS with tokens
++?

I can start drafting the initial API and component structure so we can review it together before integrating it into Checkbox #4208 and Input #4219 that we already started working on. I don't think it would cause any merge conflicts having these PRs open for a little longer while building this foundation as these are all new files. If anyone sees any blockers or has thoughts before I start, feel free to jump in 🙏

[pomfrida]

Component Overview

Field: Vertical Layout - Label Above Input:

• Input.new (Phase 1) ✅
• TextField.new
• Textarea.new
• NativeSelect.new
• Search.new ?
• Datepicker.new
• Autocomplete.new

Field: Inline Layout - Label Beside Input:

• Checkbox.new (Phase 2) ✅
• Radio.new
• Switch.new

ValidationMessage:

• All components using Field
• All components using Fieldset + hooks

Hooks:

• useCheckboxGroup
• useRadioGroup

Fieldset:

• Checkbox groups
• Radio groups
• Any grouped form inputs