ba-form

ba-form is used to handle form interactions when using our other form elements

Figma

GitHub

Storybook

Live Demo

Custom required error message

Submit

<ba-form>
  <ba-input-text label="First Name" name="firstName" hint-text="Your first name" required>
    <p slot="error">Custom required error message</p>
  </ba-input-text>
  <ba-input-text label="Last Name" name="lastName" hint-text="Your last name" required></ba-input-text>

  <ba-button variant="primary">Submit</ba-button>
</ba-form>

Guidelines

Minimise cognitive load by using a single column for simpler flows
Ensure responsiveness so that when multi-column layouts are used, they gracefully collapse into a single column on smaller devices
Validate suitability of multi-column layouts by conducting user research to confirm they’re effective for users

Accessibility

It's important to maintain the order of headings so that they appear in a logical order in the page. Screen readers (and other assistive technology) rely on headings to navigate and understand structure of pages.

Code

Validation

`ba-form` will validate the inputs by default. If you need to do some custom validation on the form, listen for the `baFormSubmit` event, and call `event.preventDefault()`. This will stop the form from performing its own validation allowing you to do anything custom thats needed.

If you would still like the form to perform it's own validation simply call the validateForm() method on ba-form. If you have set any of the inputs to invalid with your custom validation, ba-form will pick this up and show it's invalid state after calling validateForm()

In the majority of cases if you are using all native BAgel inputs you should only have to listen to the baFormValid event which will let you know if the form is valid, and emit out all of the forms data.

Retrieving the form data

To get the inputted form data from `ba-form` simply listen for the `baFormValid` event. This event will emit out all of the form data and whether the form is valid or not.

baFormSubmit does not emit out any data, as it is used to just let you know that the form has been submitted, and now is the time to perform any custom validation if you so wish. Due to this it is still advised to call the validateForm() method on ba-form at the end of your custom validation. This ensures that ba-form picks up any invalid states that have been set on the inputs, and will get all of the form data for you and emit it out.

Properties & Attributes

Property	Attribute	Description	Type	Default
`errorHeadingLevel`	`error-heading-level`	Heading tag for the error message	`"2" \| "3" \| "4" \| "5" \| "6" \| undefined`	`'3'`
`hideErrorMessage`	`hide-error-message`	Hides the default message	`boolean \| undefined`	`false`

Events

Event	Description	Type
`baFormSubmit`	Emitted when when the form is submitted	`Event`
`baFormValid`	Emitted when when the form is validated. Emits out any form data and if the form is valid	`CustomEvent<FormValid>`

Methods

validateForm() => Promise<void>

Validate the form

Returns

Type: Promise<void>

reset() => Promise<void>

Resets the input back to its initial value

Returns

Type: Promise<void>

Slots

Slot	Description	Permitted elements
Unnamed slot	Elements will render in the body of the component	`<ba‑button>`, `<ba‑card>`, `<ba‑checkbox>`, `<ba‑checkbox‑card>`, `<ba‑checkbox‑list>`, `<ba‑content>`, `<ba‑flex>`, `<ba‑form‑group>`, `<ba‑form‑group‑dropdown>`, `<ba‑grid>`, `<ba‑grid>`, `<ba‑input>`, `<ba‑input‑date>`, `<ba‑input‑datepicker>`, `<ba‑input‑email>`, `<ba‑input‑number>`, `<ba‑input‑password>`, `<ba‑input‑phone‑number>`, `<ba‑input‑stepper>`, `<ba‑input‑text>`, `<ba‑input‑textarea>`, `<ba‑input‑typeahead>`, `<ba‑input‑upload>`, `<ba‑radio‑group>`, `<ba‑select>`, `<fieldset>`
`"error-message"`	Content for the default error message	`<ba‑content>`
`"custom-message"`	Content for the default error message	`<ba‑message>`

Parent components

ba-form can be slotted into:

Permitted ARIA roles

None

Usage

Basic example

Basic example showing how to use the form and trigger validation.

Example of ba-form

<ba-form>
  <ba-input-text label="First Name" name="firstName" required></ba-input-text>
  <ba-input-text label="Last Name" name="lastName" required></ba-input-text>
  <ba-button>Submit</ba-button>
</ba-form>

Custom layout

Example with a custom layout using ba-grid

Custom layout

<ba-form>
  <ba-grid columns-800vw="2">
    <ba-input-text
      label="First Name"
      name="firstName"
    ></ba-input-text>
    <ba-input-text
      label="Last Name"
      name="lastName"
      required
    ></ba-input-text>
  </ba-grid>
  <ba-button>Submit</ba-button>
</ba-form>

Custom error with success message

Example with a custom error message and a success message.

Custom error and success message.

<ba-form>
  <ba-content slot="errorMessage">
    <p>Custom error message</p>
  </ba-content>

  <ba-message variant="success" slot="customMessage" hidden>
    <h3 slot="heading">Form submitted successfully</h3>
    <ba-link href="#" slot="action">Click here to proceed</ba-link>
  </ba-message>

  <ba-input-text label="First Name" name="firstName" required></ba-input-text>
  <ba-input-text label="Last Name" name="lastName"></ba-input-text>

  <ba-button>Submit</ba-button>
</ba-form>

<script>
document.addEventListener('baFormValid', (e) => {
  if (e.detail.valid) {
    const form = document.querySelector('ba-form')
    form.setAttribute('hide-error-message', '')

    const message = document.querySelector('ba-message')
    message.removeAttribute('hidden')

    // Get the data
    const formData = e.detail.data
  }
})
</script>

Custom validation

Example of how to perform custom validation.

ba-form with custom validation.

<ba-form>
  <ba-input-text label="First Name" name="firstName" required></ba-input-text>
  <ba-input-text label="Last Name" name="lastName"></ba-input-text>

  <ba-button>Submit</ba-button>
</ba-form>

<script>
document.addEventListener('baFormSubmit', (e) => {
  e.preventDefault()
  //
  // Perform any captcha validation
  //
  // Then perform any custom validation
  //
  // Finally run the forms own validation.
  // This ensures the form picks up on any invalid states that you may have set above.
  // It will also emit out all of the forms data and whether the form is valid.
  form.validateForm()
})

// Listener for retrieving the data and checking if the form is valid
document.addEventListener('baFormValid', (e) => {
  // Check if the form is valid
  if (!e.detail.valid) {
    return
  }

  // Get the form data
  const formData = e.detail.data
})
</script>

Preventing ba-buttons triggering the baFormSubmit event

When a form contains multiple buttons, you may not want all of them to submit the form. Ba-form will ignore ba-buttons with the no-submit attribute. Note: because there are multiple ways to submit a form, avoid relying solely on this attribute to prevent form submission; instead, monitor the baFormSubmit event.

A form that includes multiple buttons: a submit button, which allows submission, and a reset button with a no-submit attribute, preventing ba-form from submitting

<ba-form>
  <ba-grid>
    <ba-input-text
      label="First Name"
      name="firstName"
    ></ba-input-text>
    <ba-input-text
      label="Last Name"
      name="lastName"
      required
    ></ba-input-text>
  </ba-grid>
  <ba-button>Submit</ba-button>
  <ba-button variant="secondary" no-submit>Reset</ba-button>
</ba-form>