Design System Components
Last Updated:
The design system is the central UI component library for http://VA.gov . You can find it on the design.va.gov components overview page. 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 actions:
The component itself creates a
CustomEvent
namedcomponent-library-analytics
indicating the component name, action, and any additional metadataAn event listener attached to http://VA.gov listens for that custom event and routes it to the dataLayer.
If a component isn’t tracking an interaction or is missing certain parameters, please enter a /support
ticket with Analytics & Insights in the #vfs-platform-support Slack channel.
Sensitive Form Components
Components determined to potentially handle sensitive information will have analytics turned off by default.
Many 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:
va-checkbox
va-checkbox-group
va-date
va-file-input
va-loading-indicator
va-memorable-date
va-number-input
va-privacy-agreement
va-progress-bar
va-radio
va-segmented-progress-bar
va-select
va-text-input
va-text-area
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.
To enable analytics for these components, set the prop enable-analytics
(boolean) on the component.
Non-Sensitive Components
All other components not listed above will have analytics turned on by default.
Components that have analytics turned on by default, will have the disable-analytics
(boolean) prop which can be set to false
when custom analytics are desired.
When the component analytics are turned off though, teams are responsible for managing those analytics themselves. Custom events tend to be where risks of upstream/future issues come from as well as adding more maintenance overhead to teams so it’s encouraged to use the built-in component analytics when possible.
Specifications
Component Name | Description of Interaction | Event Details |
va-accordion | Accordion item toggled | { action: ‘expand’ || ‘collapse’ header: text subheader: text, level: number, sectionHeading: text } |
va-additional-info | Toggle open/closed | { action: ‘expand’ || ‘collapse’, triggerText: string } |
va-alert | Anchor link in body clicked | { action: ‘linkClick’, clickLabel: string, headline: string, status: string, backgroundOnly: boolean, closeable: boolean } |
va-alert-expandable | Toggle open/closed | { action: ‘expand’ || ‘collapse’, triggerText: string } |
va-banner | Dismiss clicked | { action: ‘close’, headline: string } |
va-breadcrumbs | Link clicked | { action: ‘linkClick’, clickLabel: string, clickLevel: number, totalLevels: number } |
va-button | Button clicked | { action: ‘click’, type: secondary || primary, label: text } |
va-button-pair | Button clicked | { action: ‘click’, type: secondary || primary, label: text } |
va-checkbox | Input checked/unchecked | { action: ‘change’, label: string, description: string, required: boolean, checked: boolean } |
va-checkbox-group | Input checked/unchecked | { action: ‘change’, label: string, optionLabel: string, required: boolean } |
va-date | Fields lose focus | { action: ‘blur’, year: number, month: number || string day: number, month-year-only: boolean } |
va-file-input | Input updated | { action: ‘change’, label: string, } |
va-link | Link clicked | { action: ‘click’, label: string } |
va-loading-indicator | Loading indicator removed | { action: ‘displayed’, displayTime: Date, message: string } |
va-maintenance-banner | Dismiss clicked | { action: ‘close’, header: string, upcomingWarnStartDateTime: Date, maintenanceStartDateTime: Date, maintenanceEndDateTime: Date, displayedContent: string } |
va-memorable-date | Fields lose focus | { action: ‘blur’, label: string, year: number, month: number || string day: number, } |
va-modal | Modal displayed | { action: ‘show’, status: string, title: string, primarybuttonText: string, secondaryButtonText: string } |
Primary button clicked | { action: ‘click’, clickLabel: string, status: string, title: string, } | |
Secondary button clicked | { action: ‘click’, clickLabel: string, status: string, title: string, } | |
va-notification | Link clicked | { action: ‘linkClick’, clickLabel: string, type: string, headline: string, } |
Notification closed | { action: ‘close’, type: string, headline: string, } | |
va-number-input | Fields lose focus | { action: ‘blur’, label: string, value: string, } |
va-official-gov-banner | Banner opened/closed | { action: ‘expand’ || ‘collapse’, } |
va-on-this-page | Link clicked | { action: click, click-text: string } |
va-pagination | Link clicked | { action: ‘linkClick’, event: string, page-number: number } |
va-privacy-agreement | Checkbox checked/unchecked | { action: ‘click’, checked: boolean } |
va-progress-bar | Component rendered | { action: ‘change’, label: string, percent: number } |
va-promo-banner | Banner closed | { action: ‘close’, text: string, type: string, } |
Link clicked | { action: ‘linkClick’, text: string, href: string, type: string } | |
va-radio | Radio option selected | { action: change, label: string, optionLabel: string, required: boolean } |
va-search-input | Search loses focus | { action: ‘blur’, value: string, } |
Submit clicked | { action: ‘click’, value: string, } | |
va-segmented-progress-bar | Component rendered | { action: ‘change’, current: number, total: number } |
va-select | Select change | { action: ‘change’, label: string, selectLabel: string } |
va-telephone | Number clicked | { action: ‘click’, contact: string, extension: string } |
va-text-input | Field loses focus | { action: ‘blur’, label: string, value: string, } |
va-text-area | Field loses focus | { action: ‘blur’, label: string, value: string, } |
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.