Tracking attributes and events

Pages in this section

Descriptions of what the tracking script adds to Design System 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'
});

The properties used in this event are:

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>

The slug uses all of the text on the button, including text that is visually hidden. For example, you might have an icon-only button that uses hidden text to help users of assistive technology.

<button type="button" class="ds_button" data-button="button-search">
    <span class="visually-hidden">Search</span>
    <svg class="ds_icon" aria-hidden="true" role="img"><use href="/path/to/icons.stack.svg#search"></use></svg>
</button>

Category list

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

External links

External links get a data-navigation attribute of link-external.

<a href="https://www.gov.scot/policies/climate-change/emissions-trading-scheme/" data-navigation="link-external">Emissions Trading Scheme</a>

Section identifiers

Links get a data-section attribute whose value is the text of the nearest preceding heading element. Heading elements are HTML headings H1 to H6 and elements with a class of ds_accordion__button.

If a link has a preceding element that has a class of either ds_page-header or ds_layout__header, the tracking script will look for a heading element inside that element.

Links inside nav elements and elements with a class of ds_metadata are not processed.

<h2>Young Scot cards</h2>

<p>If you have a <a href="/young-scot-card" data-section="Young Scot cards">Young Scot card</a>, and you live on a Scottish island, you'll be sent 4 free ferry vouchers each year while you're 16, 17 and 18.</p>

Notification banner

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>

Phase banner

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 (dropdown)

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' });

Sequential navigation

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>

Side navigation

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/scottish-government.svg" alt="Scottish Government">
    </a>

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

Site footer

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.

Site navigation

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>

Task list

Links to tasks within task lists get a data-navigation attribute whose value is tasklist.

<a class="ds_task-list__task-link" href="#" data-navigation="tasklist">Conditions <span class="visually-hidden">(Completed)</span></a>

The "skip to first incomplete section" link in a task list gets a data-navigation attribute whose value is tasklist-skip.

<a href="#task2" class="js-task-list-skip-link" data-navigation="tasklist-skip">Skip to first incomplete section</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 of 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 and support

If you need help or support you can e-mail us at designsystem@gov.scot

There is a problem

Thanks for your feedback

Was this helpful?

Yes

Your comments

Your feedback helps us to improve this website. Do not give any personal information because we cannot reply to you directly.

Choose a reason for your feedback

Your comments

Your feedback helps us to improve this website. Do not give any personal information because we cannot reply to you directly.

Yes, but

Choose a reason for your feedback

Your comments

Your feedback helps us to improve this website. Do not give any personal information because we cannot reply to you directly.

Information

Information

Accordion

Autocomplete

Back to top

Breadcrumbs

Button

Category list

Checkboxes

Contact details

Error message

Error summary

Hide this page

Inset text

Links

External links

Section identifiers

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

Task list

Text input

Textarea

Warning text

Feedback, help and support

There is a problem