Forms

The eds-form component provides a declarative, JSON-driven form system with built-in validation, conditional fields, grouped sections, and analytics tracking.

When to Use

Scenario	Approach
Simple data capture (1-5 fields)	Single `eds-form` with a flat `fields` array
Multi-section input (5+ fields)	Use `groups` to organize fields into labeled sections
Conditional flows	Add `condition` rules to fields so they show/hide based on other field values
File uploads	Use `type: "dropzone"` or `type: "file"` field types
Surveys & ratings	Use `type: "rating"` or `type: "nps"` field types

Basic Form

Pass fields as a JSON array. Each field needs at minimum a name, label, and type:

Field Types

The form supports all eds-input-field types plus special types:

Type	Description
`text`	Single-line text input
`email`	Email with format validation
`password`	Password with masked input
`number`	Numeric input with min/max/step
`textarea`	Multi-line text area
`select`	Dropdown select with options
`checkbox`	Single or grouped checkboxes
`radio`	Radio button group
`range`	Slider input
`file`	File picker (`eds-input-file`)
`dropzone`	Drag-and-drop file upload (`eds-input-dropzone`)
`rating`	Star rating (`eds-rating`)
`nps`	Net Promoter Score 0-10 scale (`eds-nps`)
`hidden`	Hidden field (not rendered, included in submission)

Validation

Fields validate in real-time as the user types. The form prevents submission until all required fields pass validation.

Required Fields

Custom Validation

Fields support minLength, maxLength, min, max, and pattern-based validation. Error messages display inline below each field.

Error Handling

When submission fails validation:

An error banner appears at the top of the form
Each invalid field shows its specific error message
Re-validation happens as the user corrects input
The submit button re-enables once all errors are resolved

Grouped Fields

Organize complex forms into sections using groups:

Conditional Fields

Show or hide fields based on other field values using condition rules:

Form Styles

Style	Description
`default`	Standard layout, no background
`shadow`	Card-style with shadow elevation
`brand`	Brand-themed with accent colors

Handling Submissions

Listen for the form event. The event detail contains the submission data and validation status:

const form = document.querySelector('eds-form');
form.addEventListener('form', (e) => {
  const { event, validated, value, success } = e.detail;

  if (event === 'submit' && validated) {
    // All fields passed validation
    console.log('Form data:', value);
  }

  if (event === 'input') {
    // Real-time field change
    console.log('Field changed:', e.detail.field, e.detail.value);
  }
});

Pre-populating Data

Use initData to populate the form with existing values:

Or programmatically:

const form = document.querySelector('eds-form');
form.setData({ firstName: 'Nikolaos', email: 'user@ebrains.eu' });

Analytics

Every form interaction is tracked automatically:

Action	Event
Field input	`{ tag: 'eds-form', name: 'fieldName', action: 'input' }`
Non-validated submit	`{ tag: 'eds-form', name: 'submit/non-validated', action: 'click' }`
Validated submit	`{ tag: 'eds-form', name: 'submit/validated', action: 'click' }`

Best Practices

Keep forms short — split complex flows into steps using eds-steps
Use groups for forms with more than 5 fields
Always set required on fields that must be filled
Provide hint text for fields with specific format requirements
Use condition on fields to reduce visual clutter
Show a success toast or alert after submission