ba-form
ba-form is used to handle form interactions when using our other form elements
Custom required error message
- 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
Further reading:
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.
Further reading
2 types of errors can be shown when ba-form is used.
- The first is the individual form field errors. These are shown if the form fields validation fails when calling
validateFormmethod. - The second type is the form error that gets shown at the top of the form. This error only shows if one of the form field within the form is invalid.
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.
<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>