Using web components

What is a web component

A web component is a custom HTML element with its own styling and behavior. It works in any JavaScript framework or library, or in plain HTML.

All VA Design System web components begin with a va- prefix. You use them like any other HTML element, setting attributes and placing content inside the tags:

<va-alert status="info">
  <h2 slot="headline">Your application is in progress</h2>
  <p>You can continue your application at any time.</p>
</va-alert>

Before using a component, load the web component library in your project. Review Load the Web Component library for setup steps.

Each web component keeps its markup and styles inside a shadow DOM, so your page styles don’t change how the component looks. Some components also accept your own content through slots, like the headline slot in the example above.

Why use web components

Use VA Design System web components wherever they meet your needs instead of building your own similar components. We maintain these components to give VA teams a set of vetted and tested building blocks.

The benefits of using Design System web components include:

• They work in any JavaScript framework, or with no framework at all
• They use consistent syntax across frameworks and projects
• They are actively maintained, and new features and fixes are added to the web components

If our components do not meet your needs, we would love to hear about it. Reach out to us in Slack at #platform-design-system or submit a bug report . And if you are interested in contributing to the Design System, review how to contribute a new component to the design system.

Vanilla JavaScript applications

Once the web component library is loaded, you can use any component directly in HTML, like <va-alert>, as long as you only need to set string, number, or boolean attributes.

If a component has a property that takes an object or array, set it with JavaScript instead of an HTML attribute. To respond to a component’s events, add an event listener. Examples of both are in the sections below.

We try to avoid object and array properties so components are easier to use in static HTML pages.

React applications

React applications have an option of either using the web component directly like <va-alert> or importing the React binding for the web component which would look like this <VaAlert>. Both of these implementations render as web components though.

How to choose to use the vanilla component or React binding?

If either of these is true, we recommend using the React binding for ease of use:

• You must pass in a function, object, or array to a web component’s properties
• You must use custom events

If you are not sure if you need either of those features, refer to the web component’s Storybook documentation to review its events and properties.

Importing a React binding of a web component

Bindings are component wrappers that allow our web components to work as first-class React components. This allows them to handle custom events and to pass in more than primitives to a web component’s properties.

Example of importing the React binding of a web component:

import { VaBreadcrumbs } from "@department-of-veterans-affairs/component-library/dist/react-bindings";

const breadcrumbs = [
  { href: "/", label: "VA.gov home" },
  { href: "/health-care", label: "Health care" },
];

<VaBreadcrumbs breadcrumbList={breadcrumbs} />;

The equivalent vanilla web component version using <va-breadcrumbs> would be this:

<va-breadcrumbs></va-breadcrumbs>

<script>
  const component = document.querySelector("va-breadcrumbs");
  component.breadcrumbList = [
    { href: "/", label: "VA.gov home" },
    { href: "/health-care", label: "Health care" },
  ];
</script>

It can be more convenient to use the React binding version of the web component in React when a function, object, or array is needed to be passed into a prop. But if you don’t require passing in a function, object, or array or listening to events, use the vanilla web component and avoid an import entirely.

Custom events

Some of the Design System web components allow for custom events.

If the web component has a custom event that you need to use and you’re using the React binding, you will need to prefix events with on. Given an event named vaChange, use onVaChange.

import { VaCheckbox } from "@department-of-veterans-affairs/component-library/dist/react-bindings";

const handleChange = (event) => {
  console.log(event.detail);
};

<VaCheckbox label="Sign up for email updates" onVaChange={handleChange} />;

If the web component has a custom event that you need to use and you’re not using the React binding, you will add an event listener using the event name as the event type:

<va-checkbox label="Sign up for email updates"></va-checkbox>

<script>
  const element = document.querySelector("va-checkbox");
  const handleChange = (event) => {
    console.log(event.detail);
  };
  element.addEventListener("vaChange", handleChange);
</script>

For more information about custom events for specific components, refer to the Storybook documentation.

Analytics events

Many of our web components fire a component-library-analytics event that sends component interactions to the analytics data layer.

• Most components fire this event by default. Add the disable-analytics attribute to turn it off.
• Form components, such as va-text-input and va-checkbox, only fire this event when you add the enable-analytics attribute.

Check a component’s Storybook documentation to see which attribute it supports. The handler for the Google Analytics event exists in vets-website.

Native events

Some of our web components utilize native HTML DOM events such as click and blur. We prefer to use native events when possible because it is easier for teams to test and may not require the use of React bindings.

To use native events in JSX, they must be prefixed with on and use camel case. Given the native blur event, use onBlur.

An example using the click event in JSX:

<va-button text="Edit" onClick={(event) => console.log(event.target)} />

To use native events in vanilla JavaScript, they can be used inline and prefixed with on or by adding an event listener using the event name as the event type.

An example using the blur event in vanilla JavaScript:

<va-button text="Edit" onblur="handleBlur(event)"></va-button>

Another example using the blur event in vanilla JavaScript:

<va-button text="Edit"></va-button>

<script>
  const element = document.querySelector("va-button");
  element.addEventListener("blur", (event) => {
    console.log(event.target);
  });
</script>

For more information about native events in a specific component, refer to the Storybook documentation.