Pages in this section

Guidance

Tracking

The Design System adds data attributes to components to help with analytics tracking.

The Design System has a script that adds ‘data attributes’ to components. Analytics software can use these data attributes to track user behaviour and measure performance. The script adds data attributes automatically, but developers still have some control over them.

Calling the function tracking.init() adds data attributes to all Design System components.

The script logic picks:

the attribute name from a set of broad categories
the attribute value, derived from the context the component is used in

For example, this is some markup for a simple Design System button:

<button class="ds_button">
    Start here
</button>

The script gives that button a data-button attribute with a value that uses the button’s text:

<button class="ds_button" data-button="button-start-here">
    Start here
</button>

The simplest use of the script is to call tracking.init() after the DOM is loaded. In some cases, you might want to have more control over:

the values used
what gets data attributes added

Custom data attribute values

The developer can set the data attribute manually in the component’s markup. The script will only add a data attribute if one is not already there.

For example, if you had a button with a very long text, you might want to shorten that attribute value. If you specify the data-button attribute in your markup before calling tracking.init(), the script will not change that value.

<button class="ds_button" data-button="button-start-here">
    Really super duper start here
</button>

Add data attributes to new components added to the page

If new components are added to the DOM after calling tracking.init(), they will not automatically have these data attributes. In most cases, it will be safe to call tracking.init() again. But, it is also possible to restrict the addition of data attributes to a particular DOM node by using an optional ‘scope’ parameter.

const myContainer = document.getElementById('my-container');

// ... add elements to myContainer

tracking.init(myContainer);

Add data attributes to specific component types

You can add data attributes to specific component types instead of adding them to everything.

In general this is less useful than restricting the addition of data attributes to a particular DOM node, but it is available if you need it.

tracking.add.accordions()

This also supports the use of a ‘scope’ parameter. Without a scope parameter, the script will apply to the whole page (the document element).

tracking.add.accordions(document.getElementById('my-container'));

How tracking handles different components

Accordion

Accordion header buttons get a data-accordion attribute whose value uses the pattern accordion-[index]-[open/close] where the index is one-based. Opening and closing an accordion panel updates that data attribute to denote the correct action (opening or closing).

<button class="ds_accordion-item__header-button js-accordion-button" data-accordion="accordion-open-1">
   Healthcare for veterans
   <span class="ds_accordion-item__indicator"></span>
</button>

If an accordion has an ‘open all’ button, that button gets a data-accordion attribute whose value uses the pattern accordion-[open/close]-all. This attribute is updated to denote the correct action when accordion panels are opened or closed.

<button data-accordion="accordion-open-all" type="button" class="ds_link  ds_accordion__open-all  js-open-all">Open all <span class="visually-hidden">sections</span></button>

Autocomplete

When a user selects an autocomplete suggestion, a custom event is triggered. This event is slightly different for keyboard and pointer interactions, but the data is the same.

window.dataLayer.push({
    event: 'autocomplete',
    searchText: 'foo',
    clickText: 'Working with football organisations',
    resultsCount: 6,
    clickedResults: 'result 2 of 6'
});

searchText: User input from the form field
clickText: Text of the selected suggestion
resultsCount: Number of suggestions provided for this search text
clickedResults: Position of the selected suggestion in the list of suggestions

Back to top

<a href="#page-top" class="ds_back-to-top__button js-initialised" data-navigation="backtotop">Back to top</a>

Breadcrumbs

Breadcrumb links get a data-navigation attribute whose value uses the pattern breadcrumb-[index] where the index is one-based.

<a class="ds_breadcrumbs__link" href="#" data-navigation="breadcrumb-1">Home</a>

Button

Buttons get a data-button attribute whose value uses the pattern button-[slug of the button text].

<button class="ds_button" data-button="button-start-here">
    Start here
</button>

Category list links get a data-navigation attribute whose value uses the pattern category-item-[index] where the index is one-based.

<a href="#" class="ds_category-item__link" data-navigation="category-item-3">Farming and rural issues</a>

Checkboxes

Checkboxes get a data-form attribute whose value uses the pattern checkbox-[checkbox ID].

<input class="ds_checkbox__input" id="education" type="checkbox" data-form="checkbox-education">

When a user changes the state of a checkbox or if it is already checked, its state is added to the data attribute.

<input class="ds_checkbox__input" id="education" checked type="checkbox" data-form="checkbox-education-checked">

Contact details

Social media links inside contact detail components get a data-navigation attribute whose value uses the pattern contact-details-[slug of the social media name].

<a class="ds_contact-details__social-link" href="#" data-navigation="contact-details-facebook">Facebook</a>

Email links inside contact detail components get a data-navigation attribute whose value is contact-details-email.

<a href="mailto:designsystem@gov.scot" data-navigation="contact-details-email">designsystem@gov.scot</a>

Error message

Error messages get a data-form attribute whose value uses the pattern error-[ID of the field that has the error].

In the case of a radio button group, the attribute uses the pattern error-[name of the radio group].

<p class="ds_question__error-message" data-form="error-more-detail">This field is required</p>

Error summary

Links in error summaries get a data-form attribute whose value uses the pattern error-[ID of the field that has the error].

<a href="#resolve" data-form="error-resolve">Did this resolve your issue?</a>

Hide this page

Hide this page buttons get a data-navigation attribute of hide-this-page.

<a href="http://bbc.co.uk/weather" data-altlink="https://www.google.co.uk" class="ds_hide-page__button  ds_button  js-hide-page" data-navigation="hide-this-page"><strong>Hide this page</strong> <span class="visually-hidden  js-enabled-text">Or press escape key to hide this page</span></a>

If the user triggers the ‘hide page’ action with their keyboard by pressing ‘Escape’ an event is pushed to the window’s dataLayer.

window.dataLayer.push({ 'event': 'hide-this-page-keyboard' });

Inset text

Links in inset text components get a data-navigation attribute of inset-link.

<div class="ds_inset-text">
    <div class="ds_inset-text__text">
        You may be able to <a data-navigation="inset-link" href="#">apply for free school meals</a> at the same time as you apply for the clothing grant.
    </div>
</div>

Links in notification banners get a data-banner attribute whose value uses the pattern banner-[bannername]-link. ‘bannername’ is either the ID of the banner or the one-based index of the banner if it does not have an ID.

<a href="#" data-banner="banner-covid-link">latest COVID guidance</a>

Close buttons in notification banners get a data-banner attribute whose value uses the pattern banner-[bannername]-close. ‘bannername’ is either the ID of the banner or the one-based index of the banner if it does not have an ID.

<button class="ds_notification__close  js-close-notification" type="button" data-banner="banner-covid-close">Close this notification</button>

Pagination

Pagination links get a data-search attribute whose value uses the pattern pagination-[slug of the link text].

<a href="#" class="ds_pagination__link" data-search="pagination-11">11</a>

<a href="#" class="ds_pagination__link" data-search="pagination-prev">Prev</a>

“Load more” links in pagination components get a data-search attribute of pagination-more.

<button class="ds_button" data-search="pagination-more">Load more</button>

Links in phase banners get a data-banner attribute whose value uses the pattern banner-[bannername]-link. ‘bannername’ is either the slug of the phase banner’s tag or simply ‘phase’ if the banner does not have a tag.

<a href="mailto:designsystem@gov.scot" data-banner="banner-beta-link">feedback</a>

Radio buttons

Radio buttons get a data-form attribute whose value uses the pattern radio-[radio group name]-[radio ID].

<input class="ds_radio__input" id="useful-yes" name="feedback-type" type="radio" value="yes" data-form="radio-feedback-type-useful-yes">

Search results

Links in search results get a data-search attribute whose value uses the pattern search-result-[index]/[total] where the index is one-based. The index takes the current page of results into consideration. For example, if there are 10 results per page and the user is on page 3, index ought to start at 21.

The start point of the list should be obtained from a start attribute that can be set on the list element.

The value of ‘total’ is obtained from a data-total attribute on the list element.

<a class="ds_search-result__link" href="#" data-search="search-result-1/68">Crofting community right to buy</a>

If the total not available, that part of the attribute is omitted.

<a class="ds_search-result__link" href="#" data-search="search-result-1">Crofting community right to buy</a>

Search suggestions

Search suggestions is a block found in the Search results pattern.

Links in search suggestions get a data-search attribute whose value uses the pattern suggestion-result-[index]/[total] where the index is one-based.

<a aria-label="Did you mean 'crafting'?" href="#" data-search="suggestion-result-1/2">crafting</a>

Select elements get a data-form attribute whose value uses the pattern select-[select ID].

Option elements inside selects get a data-form attribute whose value uses the pattern select-[select ID]-[slug of the option's value OR slug of the option's text].

<select class="ds_select js-has-tracking-event" id="component" data-form="select-component">
    <option data-form="select-component-null"></option>
    <option data-form="select-component-accordion">Accordion</option>
    <option data-form="select-component-breadcrumbs">Breadcrumbs</option>
    <option data-form="select-component-button">Button</option>
</select>

When a user changes selects an option an event is pushed to the window’s dataLayer with the selected option’s data-form attribute.

window.dataLayer.push({ 'event': 'select-component-button' });

The ‘previous page’ link in sequential navigation is given a data-navigation attribute whose value is sequential-previous.

<a href="#" class="ds_sequential-nav__button  ds_sequential-nav__button--left" data-navigation="sequential-previous">
    <span class="ds_sequential-nav__text" data-label="previous">
        Apply for or renew a Blue Badge
    </span>
</a>

The ‘next page’ link in sequential navigation is given a data-navigation attribute whose value is sequential-next.

<a href="#" class="ds_sequential-nav__button  ds_sequential-nav__button--right" data-navigation="sequential-next">
    <span class="ds_sequential-nav__text" data-label="next">
        Eligibility: who can have one?
    </span>
</a>

Links in side navigation get a data-navigation attribute whose value uses the pattern sidenav-[index] where the index is one-based.

<a href="#" class="ds_side-navigation__link" data-navigation="sidenav-1">Apples</a>

When there are nested pages in a side navigation, the subpages’ indexes are appended to the attribute.

<a href="#" class="ds_side-navigation__link" data-navigation="sidenav-1-2">Red apples</a>

On small screens the side navigation has an open/close toggle button. That button gets a data-navigation attribute whose value uses the pattern navigation-[open/close].This attribute is updated to denote the correct action when the side navigation is opened or closed.

<button class="ds_side-navigation__expand ds_link js-side-navigation-button" data-navigation="navigation-open">Show all pages in this section</button>

Site branding

Site branding is a block found in the Site header pattern.

The site branding logo link is given a data-header attribute whose value is header-logo.

The site branding title link is given a data-header attribute whose value is header-title.

<div class="ds_site-branding">
    <a class="ds_site-branding__logo  ds_site-branding__link" href="/" data-header="header-logo">
        <img class="ds_site-branding__logo-image" src="/assets/images/logos/digital-scotland.svg" alt="Digital Scotland">
    </a>

    <div class="ds_site-branding__title" data-header="header-title">
        Design System
    </div>
</div>

Site item links in site footers get a data-footer attribute whose value uses the pattern footer-link-[index] where the index is one-based.

<a href="/cookies/" data-footer="footer-link-2">Cookies</a>

Logo links are get a data-footer attribute whose value is footer-logo.

Links in site navigation components get a data-header attribute whose value uses the pattern header-link-[index] where the index is one-based. They are also given a data-device attribute whose value is either mobile or desktop.

<a href="/patterns/" class="ds_site-navigation__link" data-device="desktop" data-header="header-link-4">Patterns</a>

The mobile navigation’s toggle button is given a data-header attribute of header-menu-toggle.

Skip links

Links in skip links components get a data-navigation attribute whose value uses the pattern skip-link-[index] where the index is one-based.

<div class="ds_skip-links">
    <ul class="ds_skip-links__list">
        <li class="ds_skip-links__item"><a class="ds_skip-links__link" href="#main-content" data-navigation="skip-link-1">Skip to main content</a></li>
    </ul>
</div>

Tabs

Tabs get a data-navigation attribute whose value uses the pattern tab-link-[tabset index]-[tab index] where the indexes are one-based.

<a class="ds_tabs__tab-link" href="#tab2" role="tab" data-navigation="tab-link-1-2">Choosing apprenticeships</a>

Text input

Content of text inputs would not be routinely tracked through website analytics due to the risk of gathering personally identifiable information.

Text inputs get a data-form attribute whose value uses the pattern [input type]input-[input ID].

Note the use of the input elements’s type in the pattern. With this, different types if input can be identified.

<input class="ds_input" type="text" id="first-name" data-form="textinput-first-name">

<input class="ds_input" type="number" id="age" data-form="numberinput-age">

Textarea

Content of textareas would not be routinely tracked through website analytics due to the risk of gathering personally identifiable information.

Textareas get a data-form attribute whose value uses the pattern textarea-[textarea ID].

<textarea class="ds_input" rows="3" id="description" data-form="textarea-description"></textarea>

Warning text

Links in warning text components get a data-navigation attribute of warning-link.

<div class="ds_warning-text">
    <strong class="ds_warning-text__icon" aria-hidden="true">!</strong>
    <strong class="visually-hidden">Warning</strong>
    <div class="ds_warning-text__text">Stay safe by following the <a data-navigation="warning-link" href="#">advice of the emergency services</a> during a flood.</div>
</div>

Feedback, help or support

If you need any help or want to give any feedback you can e-mail us at: designsystem@gov.scot

Tracking

Custom data attribute values

Add data attributes to new components added to the page

Add data attributes to specific component types

How tracking handles different components

Accordion

Autocomplete

Back to top

Button

Checkboxes

Contact details

Error message

Error summary

Hide this page

Inset text

Notification banner

Phase banner

Radio buttons

Search results

Search suggestions

Sequential navigation

Side navigation

Site branding

Site footer

Site navigation

Skip links

Tabs

Text input

Textarea

Warning text

Feedback, help or support

Information

Information

Custom data attribute values

Add data attributes to new components added to the page

Add data attributes to specific component types

How tracking handles different components

Accordion

Autocomplete

Back to top

Breadcrumbs

Button

Category list

Checkboxes

Contact details

Error message

Error summary

Hide this page

Inset text

Notification banner

Pagination

Phase banner

Radio buttons

Search results

Search suggestions

Select (dropdown)

Sequential navigation

Side navigation

Site branding

Site footer

Site navigation

Skip links

Tabs

Text input

Textarea

Warning text

Feedback, help or support