Component

Single page notification button

A button that subscribes the user to email notifications to a page

By default, the component displays with the “Get emails about this page” state. If the js-enhancement flag is present, the component uses JavaScript to check if the user has already subscribed to email notifications on the current page. If yes, the state of the component updates accordingly.

The component does not render without the base_path parameter. The base_path is necessary for checking if an email subscription is active on page load and the creation/deletion of an email notification subscription.

When the button is clicked, the base_path is submitted to an endpoint which proceeds to check the user’s authentication status and whether they are already subscribed to the page or not. Depending on these factors, they will be routed accordingly.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path"
} %>

Accessibility acceptance criteria

  • The bell icon must be presentational and ignored by screen readers.

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

Already subscribed (preview)

If the user has already subscribed to email notifications about the current page, display the “Stop getting emails about this page” state.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  already_subscribed: true
} %>

With ga4 tracking (preview)

To add GA4 tracking, pass a ga4_data_attributes object with the necessary properties to the component. For example:-

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  ga4_data_attributes: {
    module: "ga4-link-tracker",
    ga4_link: {
      event_name: "navigation",
      type: "subscribe",
      index: {
        index_link: 1
      },
      index_total: 1,
      section: "Top"
    }
  }
} %>

With margin bottom (preview)

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having a margin bottom of 15px.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  margin_bottom: 5
} %>

With js enhancement (preview)

If the js-enhancement flag is present, the component uses JavaScript to check if the user has already subscribed to email notifications on the current page and accordingly updates its tracking attribute and (optionally) button text.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  js_enhancement: true
} %>

With button location (preview)

When there is more than one button on a page, we should specify their location so that Analytics can differentiate between them.

The location should have one of two values: top or bottom.

When this parameter is passed, its value is reflected in the data-action attribute (i.e “Unsubscribe-button-top”). When the flag is not present, data-action defaults to “Subscribe-button” or “Unsubscribe-button”, depending on the state of the button.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  js_enhancement: true,
  button_location: "top"
} %>

With custom button text (preview)

The component accepts custom button text, provided that both subscribe and unsubscribe text is provided.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  js_enhancement: true,
  button_text: {
    subscribe: "Subscribe to this page of things",
    unsubscribe: "Unsubscribe to this page of things"
  }
} %>

With skip account (preview)

If the skip_account flag is present, the button action will be set to the non GOV.UK One Login signup endpoint of /email-signup.

<%= render "govuk_publishing_components/components/single_page_notification_button", {
  base_path: "/current-page-path",
  js_enhancement: true,
  skip_account: true
} %>