Tracking attributes and events

Descriptions of what the tracking script adds to Design System components

Accordion

Accordion heading buttons get a data-accordion attribute. Its value uses the pattern accordion-[index]-[open/close] where the index is one-based.

When a user open or closes an accordion section (also known as a panel), the data attribute updates to denote the correct action (opening or closing).

<button class="ds_accordion-item__button js-accordion-button" id="panel-1-heading-button" type="button" aria-controls="accordion-item-ds1" aria-expanded="false" data-accordion="accordion-open-1" data-button="button-healthcare-for-veterans">
    Healthcare for veterans
    <span aria-hidden="true" class="ds_accordion-item__indicator"></span>
</button>

If an accordion has an ‘open all’ button, that button gets a data-accordion attribute. Its value uses the pattern accordion-[open/close]-all.

When a user opens or closes all accordion sections, the attribute updates to denote the correct action.

<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>

Links in accordion sections (panels) get a:

data-navigation attribute of accordion-link
data-section attribute with the heading for that panel

<div class="ds_accordion-item ds_accordion-item--open" id="accordion-item-ds1">
    <input type="checkbox" class="ds_accordion-item__control fully-hidden" id="panel-1" aria-labelledby="panel-1-heading" tabindex="-1">
    <div class="ds_accordion-item__header">
        <h3 id="panel-1-heading" class="ds_accordion-item__title ds_accordion-item__title--button">
            <button class="ds_accordion-item__button js-accordion-button" id="panel-1-heading-button" type="button" aria-expanded="true" aria-controls="accordion-item-ds2-body" data-accordion="accordion-close-1" data-button="button-healthcare-for-veterans">
                Healthcare for veterans
                <span aria-hidden="true" class="ds_accordion-item__indicator"></span>
            </button>
        </h3>
        <label class="ds_accordion-item__label" for="panel-1"><span class="visually-hidden fully-hidden">Show this section</span></label>
    </div>
    <div class="ds_accordion-item__body" id="accordion-item-ds2-body">
        <p>Veterans are entitled to the same healthcare as any citizen. And there are <a href="#" data-navigation="accordion-link" data-section="Healthcare for veterans">health care options and support</a> available specifically for veterans.  </p>
        <p>If you have a health condition that's related to your service, you're entitled to priority treatment based on clinical need. </p>
    </div>
</div>

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. Its 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. Its 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. Its 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. Its value uses the pattern checkbox-[checkbox ID] and a data-value attribute where the value is the ID of the checkbox.

<input class="ds_checkbox__input" id="education" type="checkbox" data-form="checkbox-education" data-value="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">

Confirmation message

Links in confirmation message components get a data-navigation attribute of confirmation-link.

<div class="ds_confirmation-message">
    <svg class="ds_confirmation-message__icon  ds_icon  ds_icon--24" aria-hidden="true" role="img">
        <use href="/assets/images/icons/icons.stack.svg#check_circle"></use>
    </svg>
    <h3 class="ds_confirmation-message__title">
        Landlord added successfully
    </h3>
    <div class="ds_confirmation-message__body">
        <p>You have added the landlord <strong>John Smith</strong> to the application. <a href="#" data-navigation="confirmation-link">Go back to the summary page.</a></p>
    </div>
</div>

Contact details

Social media links inside contact detail components get a data-navigation attribute. Its 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. Its value is contact-details-email.

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

Details

Details 'summary' elements get a data-accordion attribute. Its value uses the pattern detail-[open/close]. Opening and closing a details component updates that data attribute to denote the correct action (opening or closing).

<summary class="ds_details__summary" data-accordion="detail-open">
    I cannot sign in
</summary>

Links in details components get a:

data-navigation attribute of details-link
data-section attribute with the detail's summary value

<details class="ds_details" data-module="ds-details" open="">
    <summary class="ds_details__summary" data-accordion="detail-close">
        System requirements
    </summary>
    <div class="ds_details__text">
        Requires a computer running an operating system. The computer must have some memory and ideally some kind of long-term storage. An input device as well as some form of output device is recommended. <a href="#" data-navigation="details-link" data-section="System requirements">How to find specifications for your computer</a>.
    </div>
</details>

Error message

Error messages get a data-form attribute. Its 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. Its value uses the pattern error-[ID of the field that has the error]. Links also get a data-section attribute with the heading of the Error summary panel.

<a href="#resolve" data-form="error-resolve" data-section="There is a problem">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. Its value is the text of the nearest preceding heading element. Heading elements are HTML headings H1 to H6 and those with a class of ds_details__summary.

The tracking script will look for a heading element inside the preceding element if it has a class of:

ds_page-header
ds_layout__header
ds_accordion-item__header

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. Its value uses the pattern banner-[bannername]-link. ‘bannername’ is either the:

ID of the banner
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. Its value uses the pattern banner-[bannername]-close. ‘bannername’ is either the:

ID of the banner
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>

Page metadata

Links in page metadata get a data-navigation attribute. Its value uses the pattern [key]-[index] where the key is the slug of the metadata item's title and the index is one-based.

<dt class="ds_metadata__key">
    Topic
</dt>
<dd class="ds_metadata__value">
    <a data-navigation="topic-1" href="/arts-culture-and-sport/">Arts, culture and sport</a>, 
    <a data-navigation="topic-2" href="/public-sector/">Public sector</a>
</dd>

Pagination

Pagination links get a data-search attribute. Its 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. Its value uses the pattern banner-[bannername]-link. ‘bannername’ is either:

the slug of the phase banner’s tag
‘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. Its value uses the pattern radio-[radio group name]-[radio ID] and a data-value attribute where the value is the ID of the radio button.

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

Search results

Links in search results get a data-search attribute. Its 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 is 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 result 'part of' links

These secondary links appear within a search result.

The data-section attribute contains the link text for the search result.

The data-search attribute takes the form search-parent-link-[index]/[total]. This indicates the position of the search result within the list of results.

<a href="/adult-disability-payment" data-section="How to apply for Adult Disability Payment" data-search="search-parent-link-3/284">Adult Disability Payment</a>

Search suggestions

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

Links in search suggestions get a data-search attribute. Its 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. Its value uses the pattern select-[select ID].

Option elements inside select components get a data-form attribute. Their 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 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. Its 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. Its 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. Its 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. Its 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. Its value is header-logo.

The site branding title link is given a data-header attribute. Its 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. Its 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 get a data-footer attribute. Its value is footer-logo.

Site navigation

Links in site navigation components get a data-header attribute. Its 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. Its 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>

Summary list

Action buttons can be either a button element or a link.

Buttons get a data-button attribute. Its value uses the pattern button-[label]-[question] where the label is the label of the button and the question is what the button's action applies to.

Links get a data-navigation attribute. Its value uses the pattern navigation-[label]-[question] where the label is the link text and the question is what the link's action applies to. Links will also get a data-section attribute with the name of the closest heading.

<button type="button" class="ds_link" aria-describedby="item-1-key" data-button="button-change-have-you-had-the-grant-3-times-or-more-since-1-may-2022">Change</button>

<a href="#" aria-describedby="item-1-key" data-section="Your answers" data-navigation="navigation-change-have-you-had-the-grant-3-times-or-more-since-1-may-2022">Change</a>

Summary card

Summary cards have additional action buttons that apply to the whole card. These can be either a button or a link.

Buttons get a data-button attribute. Its value uses the pattern button-[label]-[index] where the label is the label of the button and the index is the order of the summary card against other cards on the page.

Links get a data-navigation attribute. Its value uses the pattern navigation-[label]-[index] where the label is the link text and the index is the order of the summary card against other cards on the page.

<button type="button" class="ds_link" aria-describedby="card-1-title" data-button="button-change-1">Change</button>

<a href="#" class="ds_link" aria-describedby="card-1-title" data-navigation="navigation-add-1">Add</a>

Tabs

Tabs get a data-navigation attribute. Its 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. Its 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. Its 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. Its 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. Its 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

Thanks for your feedback

Information