ba-form

Anatomy

Design Documentation

Live Demo

Properties and attributes

Permitted ARIA roles

• None

Slots

Parent components

ba-form can be slotted into:

• <ba‑tab‑container‑content>
• <ba‑tab‑chip‑content>
• <ba‑page‑segment>
• <ba‑hero>
• <ba‑grid>
• <ba‑flex>
• <ba‑card>

Events

Usage

Basic example

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

<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

<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.

<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>
    <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.

<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>

Guidelines

Keyboard navigation

Usage and accessibility checklist

Use this checklist to confirm the component has been configured and used correctly.

UX checklist

• Use a single column layout for simpler flows to minimise cognitive load
• When using multi-column layouts, ensure they gracefully collapse into a single column on smaller devices
• Validate suitability of multi-column layouts by conducting user research to confirm they are effective for users
• The error summary is only displayed after the user attempts to submit the form
• The error summary links to the first invalid field in the form

Accessibility checklist

• Use the error-heading-level attribute to maintain the correct heading hierarchy in the page
• The error summary heading follows the correct document hierarchy
• Individual field errors are visible and associated with their respective fields
• Focus moves to the error summary when the form is submitted with invalid fields
• ba-form is operable using a keyboard alone