Skip to main content
Skip table of contents

Design System Components

The design system is the central UI component library for VA.gov. You can find it at https://design.va.gov/components/. Many components have been updated to automatically insert events into Google Analytics for certain interactions. These auto-tracked design system components will cut down on the amount of time VFS and Platform teams spend during implementation. Also, these interactions are automatically visualized on several KPI dashboards in Domo.

Implementation Notes

This document includes dataLayer specifications for these interactions, but rarely should developers manually create these events. The components themselves should handle the process.

This implementation comprises of two main components:

  1. The component itself which creates a CustomEvent indicating the component name, action, and any additional metadata.

  2. An event listener attached to VA.gov that listens for the custom events and routes them to the dataLayer.

If a component isn’t tracking an interaction or is missing certain parameters, please enter a /support ticket with Platform Analytics & Insights.

Sensitive Form Components

Most design system components are configured to push events automatically when the components are used within the application. However, there are several components that by default do NOT trigger events due to PII or PHI concerns. These components are:

  • TextInput

  • TextArea

  • Select

  • Checkbox

  • CheckboxGroup

  • RadioButton

While these components have been reviewed by the Identity team, it is still the responsibility of the VFS team to conduct a security review before data collection of these components can begin.

Specifications

Component Name

Where Components are Implemented

Description of Interaction

Data Layer Specification

GA Event

Buttons

Global event listener for buttons

Click on a button with an appropriate CSS class

CODE
'event': 'cta-button-click' //consistently populate for ALL types of button clicks
'button-type' //'primary', 'secondary', 'default'
'button-click-label': //dynamically populate with text of button
'button-background-color': //dynamically populate with the background color of the button`

Event Action:
Primary Button CTA - {{DL - button-click-label}} - {{DL - button-background-color}}

or

Secondary Button CTA - {{DL - button-click-label}} - {{DL - button-background-color}}

Accordions

CODE
<va-accordion>

Web component only (NOT CollapsiblePanel.js)

Click to expand/collapse accordions

CODE
'event': 'int-accordion-expand', //OR 'int-accordion-collapse'
'accordion-parent-label' //accordion parent label (if there is two labels, if only one label on accordion, populate this value and make child-label undefined)
'accordion-child-label': //dynamically populate with secondary label of the accordion
'accordion-section-label': //populate with the label of the section where the accordion is present`

Event Action:
Accordion - Expand - {{CJ - Accordion Action}}

or

Accordion - Collapse - {{CJ - Accordion Action}}

Additional Info

AdditionalInfo.js

Click to expand/collapse additional info component

CODE
'event': 'int-additional-info-expand', //OR 'int-additional-info-collapse',
'additional-info-click-label': //dynamically populate with the click label of the expandable component`

Event Action:
Additional Info - Expand - {{DL - additional-info-triggerText}}

or

Additional Info - Collapse - {{DL - additional-info-triggerText}}

Alert Boxes (deprecated)

AlertBox.js

Click on a link and/or heading within an alert box or click to close

CODE
'event': 'nav-alert-box-link-click' //consistent for all links within an alert box
'alert-box-status': //dynamically populate according to the type of alert box, 'warning', 'error', 'info'
'alert-box-headline': //dynamically populate according to the top level heading of the alert box
'alert-box-headline-level': //dynamically populate with the level of the headline
'alert-box-click-label': //dynamically populate according to the click label of the link
'alert-box-background-only: //dynamically populate with boolean true\|false if alert box background only prop was used
'alert-box-closeable': //dynamically populate with true or false if the component is closeable

Substitute these for close event, use variables above

CODE
'event': 'int-alert-box-close' //consistently populate when an alert box is closed

Event Action:
Banner - Alert Box - Link - {{Click Text}}

Breadcrumbs

Breadcrumb.js

Click on a breadcrumb link

CODE
'event': 'nav-breadcrumb',
'breadcrumb-clickLabel': //dynamically populate according to the breadcrumb label clicked on
'breadcrumb-clickLevel': //level number clicked on
'breadcrumb-totalLevels': //total number of click levels
'breadcrumb-mobile-first-enabled': //boolean for if the mobile first prop is used`

Event Action:
Navigation - Breadcrumb - {{DL - breadcrumb-click-label}} - {{DL - breadcrumb-click-level}} - {{DL - breadcrumb-total-levels}}

Form Controls - Text Box

TextInput.js

TextArea.js

Input and click away from text box

CODE
'event': 'int-text-input-blur' //consistently populate for text box inputs
'text-input-label': //dynamically populate according to the label of the text box
'text-input-value': //dynamically populate with the user input text

Substitute these variables for TextArea.js

CODE
'event': 'int-text-area-blur' //consistently populate for text box inputs
'text-area-label': //dynamically populate according to the label of the text area
'text-area-value': //dynamically populate with the user input text

Event Action:
Text Box - {{DL - text-input-label}} - {{DL - text-input-value}}

Form Controls - Select box

Select.js

Selection and click away from select box

CODE
'event': 'int-select-box-option-click' //consistently populate for all select box selections
'select-box-label': //dynamically populate according to the label of the select box presented to the user
'select-box-value': //dynamically populates with the select box value selected
'select-box-required': //dynamically populates with boolean true or false, true if checkbox is required
'select-options': //dynamically populates with the options of the select box

Event Action:
Select Box ~~ {{DL - select-label}} ~~ {{DL - select-selectLabel}}

Form Controls - Checkbox

Checkbox.js

CheckboxGroup.js

Select and click away from a checkbox option

JS
'event': 'int-checkbox-option-click',
'checkbox-label': //dynamically populates according to check box label selected
'checkbox-labelAboveCheckbox': //dynamically populates according to label description presented to the user 
'checkbox-required': //dynamically populates with boolean true or false, true if checkbox is required

Substitute these variables for CheckboxGroup.js

CODE
'event': 'int-checkbox-group-option-click'
'checkbox-group-optionLabel': //dynamically populates with the label of the selected checkbox
'checkbox-group-label: //dynamically populates with the label of the checkbox group presented to the user
'checkbox-group-required': //dynamically populates with boolean true or false, true if checkboxgroup is required

Event Action:
Checkbox - {{DL - checkbox-label}} - {{DL - checkbox-option-click-label}}

Form Controls - Radio Button

RadioButton.js

Select and click away from a radio button option

CODE
'event': 'int-radio-button-option-click', //consistently populate for all radio button toggles
'radio-button-label': //dynamically populate according to the radio button label for the group presented to the user
'radio-button-optionLabel': //dynamically populate according to the radio button option selected label
'radio-button-required: //dynamically populates with boolean true or false, true if radio button is required

Event Action:
Radio Button - {{DL - radio-button-label}} - {{DL - radio-button-option-click-label}}

Modal

Modal.js

Click on a modal button

CODE
'event: 'int-modal-click',
'modal-status': this.props.status,
'modal-title': this.props.title,
'modal-primaryButton-text': this.props.primaryButton.text,
'modal-secondaryButton-text': this.props.secondaryButton.text

Event Action:
Modal - Click - {{DL - modal-status}} - {{DL - modal-title}} - {{DL - modal-primaryButtonText}} - {{DL - modal-secondaryButtonText}} - {{Click Text}}

Pagination

Pagination.js

Click to paginate

CODE
'event': 'nav-paginate-number' //if number click, 'nav-paginate-previous' if previous click, 'nav-paginate-next' if next click
'paginate-page-number': //dynamically populate according to the number the user navigated to
'maximum-page-list-length': //populate according to the maximum number of pages that can be navigated
'last-page-enabled': //populate if last page enabled prop is used

Event Action:
Navigation - Paginate - Next

or

Navigation - Paginate - Previous

or

Navigation - Paginate - Number: {{DL - Paginate Page Number}}

Progress Bars

On state change

CODE
'event': 'nav-progress-bar-change', //consistent event name for progress bar change
'progress-bar-type': 'segmented', //dynamic with type of progress bar, in this case 'segmented'
'progress-bar-current': //dynamically populate with an integer with each new change the current
'progress-bar-total': //consistently populate as an integer with the total number of segments
'progress-bar-title': //dynamically populate according to the label on the component
'progress-bar-percentage': 10 //use for standard progress bar, only in increments of 10%`

Event Action:

Promo Banner

PromoBanner.js

Click on a link within the promo banner

CODE
'event': 'nav-promo-banner-link-click'
'promo-banner-click-label': //populate according to link click text
'promo-banner-click-target': //populate according to target in component
'promo-banner-click-href': //populate according to click href
'promo-banner-closeable': //populate with true or false based on if promo banner is capable of being closed
'promo-banner-type': //populate according to banner type (icon) in component`

Event Action:
Navigation - Promo Banner - {{DL - promo-banner-type}} - {{DL - promo-banner-href}} - {{DL - promo-banner-target}} - {{DL - promo-banner-text}}


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.