govuk_publishing_components 32.1.0 → 35.0.0

data/app/views/govuk_publishing_components/components/docs/contents_list.yml

@@ -24,6 +24,7 @@ shared_accessibility_criteria:
   - link
 accessibility_excluded_rules:
   - skip-link # The examples for this component are using references to sections on the page that do not exist in examples
+uses_component_wrapper_helper: true
 examples:
   default:
     data:
@@ -65,18 +66,6 @@ examples:
           active: true
         - href: "#third-thing"
           text: Third thing
-  with_custom_aria_label:
-    description: 'An `aria-label` string should be used to contextualise the navigation for assistive technology. Defaults to `Contents` if `aria-label` is not passed.'
-    data:
-      aria_label: "Pages in this guide"
-      contents:
-        - href: "#first-thing"
-          text: First
-        - href: "#two"
-          text: Second
-          active: true
-        - href: "#third-thing"
-          text: Third thing
   nested_contents_lists:
     data:
       contents:

data/app/views/govuk_publishing_components/components/docs/contextual_breadcrumbs.yml

@@ -32,3 +32,16 @@ examples:
       inverse: true
     context:
       dark_background: true
+  with_ga4_tracking:
+    description: |
+      Adds GA4 tracking to the step by step nav header component when it is rendered as a breadcrumb. See the 
+      [ga4-link-tracker documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-link-tracker.md) for more information.
+      Note: tracking on regular breadcrumbs is enabled by default and does not require activating.
+    data:
+      ga4_tracking: true
+      content_item:
+        title: "A content item"
+        links:
+          part_of_step_navs:
+            - title: "Learn to drive a car: step by step"
+              base_path: "/micropigs-vs-micropugs"

data/app/views/govuk_publishing_components/components/docs/contextual_footer.yml

@@ -69,3 +69,46 @@ examples:
           ordered_related_items:
             - title: "Find an apprenticeship"
               base_path: "/apply-apprenticeship"
+  with_ga4_tracking:
+    description: Adds Google Analytics 4 tracking to the Related Navigation component, if it is visible.
+    data:
+      ga4_tracking: true
+      content_item:
+        title: "A content item"
+        links:
+          topics:
+          - title: Apprenticeships, 14 to 19 education and training for work
+            base_path: /browse/education/find-course
+            document_type: topic
+          - title: Finding a job
+            base_path: /browse/working/finding-job
+            document_type: topic
+          - title: Apprenticeships
+            base_path: /topic/further-education-skills/apprenticeships
+            document_type: topic
+          topical_events:
+          - title: UK-China High-Level People to People Dialogue 2017
+            base_path: /government/topical-events/uk-china-high-level-people-to-people-dialogue-2017
+            document_type: topical_event
+          related:
+          - title: Pest Control
+            base_path: /pest-control
+            document_type: contact
+          related_statistical_data_sets:
+          - title: International road fuel prices
+            base_path: /government/statistical-data-sets/comparisons-of-industrial-and-domestic-energy-prices-monthly-figures
+            document_type: statistical_data_set
+          - title: Weekly road fuel prices
+            base_path: /government/statistical-data-sets/oil-and-petroleum-products-weekly-statistics
+            document_type: statistical_data_set
+          world_locations:
+          - title: South Sudan
+            base_path: /world/south-sudan/news
+          - title: USA
+            base_path: /world/usa/news
+        details:
+          external_related_links:
+          - url: "http://media.slc.co.uk/sfe/1718/ft/sfe_terms_and_conditions_guide_1718_d.pdf"
+            title: "Student loans: terms and conditions 2017 to 2018 (PDF, 136KB)"
+          - title: The Student Room repaying your student loan
+            url: https://www.thestudentroom.co.uk/content.php?r=5967-Repaying-your-student-loan

data/app/views/govuk_publishing_components/components/docs/contextual_sidebar.yml

@@ -103,3 +103,68 @@ examples:
               title: "Russian invasion of Ukraine: UK government response"
               base_path: "/government/topical-events/russian-invasion-of-ukraine-uk-government-response"
               locale: "en"
+  with_ga4_tracking_on_related_navigation:
+    description: Adds Google Analytics 4 tracking to components within the sidebar. Currently only the Related Navigation component, Step by Step navigation component and Ukraine CTA accept this option.
+    data:
+      ga4_tracking: true
+      content_item:
+        title: "UK forces arrive to reinforce NATO’s eastern flank"
+        content_id: "a342fd46-d801-4c1e-9d8f-f41fba6da563"
+        locale: "en"
+        links:
+          ordered_related_items:
+          - title: Find an apprenticeship
+            base_path: /apply-apprenticeship
+          - title: Careers helpline for teenagers
+            base_path: /careers-helpline-for-teenagers
+          document_collections:
+          - title: Recruit an apprentice (formerly apprenticeship vacancies)
+            base_path: /government/collections/apprenticeship-vacancies
+            document_type: document_collection
+          - title: The future of jobs and skills
+            base_path: /government/collections/the-future-of-jobs-and-skills
+            document_type: document_collection
+          topical_events:
+            - content_id: "bfa79635-ffda-4b5d-8266-a9cd3a03649c"
+              title: "Russian invasion of Ukraine: UK government response"
+              base_path: "/government/topical-events/russian-invasion-of-ukraine-uk-government-response"
+              locale: "en"
+  with_ga4_tracking_on_step_by_step:
+    description: Adds Google Analytics 4 tracking to components within the sidebar. Currently only the Related Navigation component, Step by Step navigation component and Ukraine CTA accept this option.
+    data:
+      ga4_tracking: true
+      content_item:
+        title: "A content item"
+        links:
+          part_of_step_navs:
+            - title: "What to do when someone dies: step by step"
+              base_path: "/when-someone-dies"
+              details:
+                step_by_step_nav:
+                  title: 'What to do when someone dies: step by step'
+                  steps:
+                  - title: Register the death
+                    contents:
+                    - type: list
+                      contents:
+                      - text: Register the death
+                        href: "/after-a-death"
+                    optional: false
+                  - title: Arrange the funeral
+                    contents:
+                    - type: list
+                      contents:
+                      - text: Arrange the funeral
+                        href: "/after-a-death/arrange-the-funeral"
+                    optional: false
+  with_ga4_tracking_on_part_of_step_by_step_heading(s):
+    description: Adds Google Analytics 4 tracking to the "Part of" step by step heading(s) in the sidebar. Currently only the Related Navigation component, Step by Step navigation component and Ukraine CTA accept this option.
+    data:
+      ga4_tracking: true
+      content_item:
+        links:
+          part_of_step_navs:
+            - title: "Choosing a micropig or micropug: step by step"
+              base_path: "/micropigs-vs-micropugs"
+            - title: "Walk your micropig: step by step"
+              base_path: "/porgs-step-by-step"

data/app/views/govuk_publishing_components/components/docs/details.yml

@@ -36,6 +36,23 @@ examples:
           dimension20: "custom dimension"
       block: |
         We need to know your nationality so we can work out which elections you’re entitled to vote in. If you can’t provide your nationality, you’ll have to send copies of identity documents through the post.
+  with_aria_attributes:
+    description: |
+      Aria attributes can be applied to the summary element of the component.
+    data:
+      title: Works with 2 agencies and public bodies
+      summary_aria_attributes:
+        label: Attorney General's office
+      block: |
+        <ul>
+          <li>Department 1</li>
+          <li>Department 2</li>
+        </ul>
+    embed: |
+      <div>
+        <p class="govuk-body">Attorney General's office</p>
+        <%= component %>
+      </div>
   with_GTM_tracking:
     description: Applies a tracking attribute specifically for use by Google Tag Manager in [Content Publisher](https://github.com/alphagov/content-publisher).
     data:

data/app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -195,7 +195,7 @@ examples:
           document_type: 'Statistical data set'
         subtext: 'First published during the 1996 Conservative Government'
   without_top_border_on_list_element:
-    description: Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn't gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in this instances.
+    description: Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn't gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in these instances.
     data:
       remove_top_border: true
       items:
@@ -211,6 +211,23 @@ examples:
         metadata:
           public_updated_at: 2017-07-19 15:01:48
           document_type: 'Statistical data set'
+  without_top_border_on_first_list_element:
+    description: Several interfaces across GOV.UK benefit from the semantics of the document list but have their own bespoke designs, sometimes meaning that the visual border element doesn't gel with said interface. Removing it using the below attribute allows for cleaner visual fidelity in these instances.
+    data:
+      remove_top_border_from_first_child: true
+      items:
+      - link:
+          text: 'Department for Education – Statistics at DfE'
+          path: '/government/organisations/department-for-education/about/statistics'
+        metadata:
+          public_updated_at: 2017-07-19 15:01:48
+          document_type: 'Corporate information'
+      - link:
+          text: 'State-funded school inspections and outcomes: management information'
+          path: '/government/organisations/department-for-education/about/statistics'
+        metadata:
+          public_updated_at: 2017-07-19 15:01:48
+          document_type: 'Statistical data set'
   highlighted_result:
     description: Highlight one or more of the items in the list. This is used on finders to provide a 'top result' for a search. The `highlight_text` parameter is optional.
     data:

data/app/views/govuk_publishing_components/components/docs/emergency_banner.yml

@@ -7,7 +7,9 @@ body: |
 
 shared_accessibility_criteria:
   - link
-
+accessibility_excluded_rules:
+  - duplicate-id-aria # IDs will be duplicated in component examples list
+  - landmark-unique # aria-label attributes will be duplicated in component examples list
 examples:
   default:
     description: |

data/app/views/govuk_publishing_components/components/docs/error_message.yml

@@ -21,3 +21,16 @@ examples:
       items:
         - text: Error 1
         - text: Error 2
+  with_dir_attribute:
+    description: Allows the correct display of right to left languages
+    data:
+      text: "An error message displayed right to left"
+      id: "error_id_2"
+      right_to_left: true
+  with_items_and_dir_attribute:
+    description: To allow the correct display of right to left languages on error items
+    data:
+      right_to_left: true
+      items:
+        - text: Error 1 displayed right to left
+        - text: Error 2 displayed right to left

data/app/views/govuk_publishing_components/components/docs/govspeak.yml

@@ -180,11 +180,32 @@ examples:
             </tr>
           </tbody>
         </table>
+  tables_with_alignments:
+    data:
+      block: |
+        <table>
+          <thead>
+            <tr>
+              <th scope="col">Default aligned</th>
+              <th class="cell-text-left" scope="col">Left aligned</th>
+              <th class="cell-text-center" scope="col">Center aligned</th>
+              <th class="cell-text-right" scope="col">Right aligned</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>First body part</td>
+              <td class="cell-text-left">Second cell</td>
+              <td class="cell-text-center">Third cell</td>
+              <td class="cell-text-right">fourth cell</td>
+            </tr>
+          </tbody>
+        </table>
   charts:
     description: |
       The Government Statistical Service (GSS) guidance recommends [a limit of four categories as best practice for basic data visualisations](https://gss.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/#section-5).
 
-      Note that charts which have up to 7 categories, [chart with colours](http://govuk-publishing-components.dev.gov.uk/component-guide/govspeak/chart_with_colours/preview), for example, will display subsequent bars in `#3d3d3d`, `#a285d1` and the 7th bar in the default colour of `#0b0c0c` and will still meet the colour contrast requirements for adjacent colours. 
+      Note that charts which have up to 7 categories, [chart with colours](http://govuk-publishing-components.dev.gov.uk/component-guide/govspeak/chart_with_colours/preview), for example, will display subsequent bars in `#3d3d3d`, `#a285d1` and the 7th bar in the default colour of `#0b0c0c` and will still meet the colour contrast requirements for adjacent colours.
       Charts that have 8 or more categories will display additional bars in the default colour and will not meet colour contrast requirements for adjacent colours.
     data:
       block: |

data/app/views/govuk_publishing_components/components/docs/hint.yml

@@ -19,3 +19,9 @@ examples:
     data:
       text: "You qualify if you were born in the UK before June 1960."
       margin_bottom: 9
+  with_dir_attribute:
+    description: |
+      Allows the correct display of right to left languages.
+    data:
+      text: "العربيَّة"
+      right_to_left: true

data/app/views/govuk_publishing_components/components/docs/image_card.yml

@@ -205,6 +205,29 @@ examples:
       <div class="govuk-!-width-full">
         <%= component %>
       </div>
+  youtube_video:
+    description: |
+      Given a Youtube video id, the image card will render a Youtube embed instead of an image. If Javascript fails to execute for any reason, then a fallback link to the Youtube video will be rendered instead.
+
+      Youtube does not support embeds on Internet Explorer versions lower than 10. In addition, Youtube's website will block any version of Internet Explorer using it. There is therefore no fallback for IE9 and lower.
+    data:
+      youtube_video_id: "XnP6jaK7ZAY"
+      href: "/still-not-a-page"
+      youtube_video_alt: "The vision for GOV.UK"
+      context:
+        date: 2017-06-14 11:30:00
+        text: "Announcement"
+      description: "Following a news report that something has happened, further details are emerging of the thing that has happened and what that means for you."
+      extra_details: [
+        {
+          text: "Link to video transcript",
+          href: "/1"
+        }
+      ]
+    embed: |
+      <div class="govuk-!-width-full">
+        <%= component %>
+      </div>
   with_data_attributes:
     description: Data attributes can be applied as required. Note that the component does not include built in tracking. If this is required consider using the [track click script](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics/track-click.md).
     data:
@@ -296,4 +319,4 @@ examples:
     embed: |
       <div class="govuk-!-width-full">
         <%= component %>
-      </div>
+      </div>

data/app/views/govuk_publishing_components/components/docs/input.yml

@@ -183,3 +183,35 @@ examples:
         text: "Given name"
       name: given-name
       enterkeyhint: "next"
+  with_dir_attribute:
+    description: |
+      Allows the correct display of right to left languages.
+
+      By default the input element and the label both display text in a left to right direction.
+
+      When the `right_to_left` parameter of the input component is set to `true` both the input and the label, hint and error message display their content in a right to left direction. 
+    data:
+      label:
+        text: "Some input text to be displayed right to left with a label that displays in the same direction"
+      hint: "Some hint text that displays in the same text direction as the label"
+      error_message: "An error message that displays in the same text direction as the label"
+      name: rtl-input-text
+      value: "العربيَّة"
+      right_to_left: true
+
+  with_separate_dir_attributes_for_field_and_help_text:
+    description: |
+      Allows the correct display of right to left languages.
+
+      By default the input element and the label both display text in a left to right direction.
+
+      If the input field and the help text (label, hint and error messages) are required to display in different directions the `right_to_left_help` attribute can be set as false to override the `right_to_left` attribute.
+    data:
+      label:
+        text: "Some input text that displays right to left with a label that displays left to right"
+      hint: "Some hint text that displays in the same text direction as the label"
+      name: rtl-input-text
+      value: "العربيَّة"
+      right_to_left: true
+      right_to_left_help: false
+      error_message: "An error message that displays in the same text direction as the label"

data/app/views/govuk_publishing_components/components/docs/intervention.yml

@@ -14,9 +14,10 @@ accessibility_criteria: |
   - have a border colour contrast ratio of more than 4.5:1 with its background to be visually distinct
   - prevent screen readers from announcing the dismiss link icon
 
-
 shared_accessibility_criteria:
   - link
+accessibility_excluded_rules:
+  - landmark-unique # aria-label attributes will be duplicated in component examples list
 examples:
   default:
     data:

data/app/views/govuk_publishing_components/components/docs/label.yml

@@ -59,3 +59,20 @@ examples:
       html_for: "id-radio"
       hint_id: "id-radio"
       hint_text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
+  with_id:
+    description: 
+    data:
+      text: "Label with an ID"
+      id: "id-for-the-label"
+      html_for: "id-that-matches-input-6"
+  with_dir_attribute:
+    description: |
+      To allow the correct display of right to left languages.
+
+      When the `right_to_left` parameter is set to `true` any hint text displays in the same text direction as the label.
+    data:
+      text: "العربيَّة"
+      html_for: "id-that-matches-input-7"
+      hint_id: "should-match-aria-describedby-input"
+      hint_text: "Hint text displayed right to left"
+      right_to_left: true

data/app/views/govuk_publishing_components/components/docs/layout_header.yml

@@ -7,6 +7,7 @@ govuk_frontend_components:
   - header
 accessibility_excluded_rules:
   - landmark-banner-is-top-level # The header element can not be top level in the examples
+  - duplicate-id # IDs will be duplicated in component examples list
   - duplicate-id-aria # IDs will be duplicated in component examples list
   - form-field-multiple-labels # Form labels will be ambiguous in component examples list
   - landmark-no-duplicate-banner # banners will be duplicated in component examples list

data/app/views/govuk_publishing_components/components/docs/previous_and_next_navigation.yml

@@ -21,6 +21,8 @@ accessibility_criteria: |
 
 shared_accessibility_criteria:
   - link
+accessibility_excluded_rules:
+  - landmark-unique # aria-label attributes will be duplicated in component examples list
 examples:
   default:
     data:

data/app/views/govuk_publishing_components/components/docs/related_navigation.yml

@@ -306,3 +306,50 @@ examples:
               title: "Student loans: terms and conditions 2017 to 2018 (PDF, 136KB)"
             - title: The Student Room repaying your student loan
               url: https://www.thestudentroom.co.uk/content.php?r=5967-Repaying-your-student-loan
+  with_ga4_tracking:
+    description: Adds Google Analytics 4 tracking to the component, using the [GA4 link tracker](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-link-tracker.md).
+    data:
+      ga4_tracking: true
+      content_item:
+        links:
+          ordered_related_items:
+            - title: Find an apprenticeship
+              base_path: /apply-apprenticeship
+            - title: Training and study at work
+              base_path: /training-study-work-your-rights
+            - title: Careers helpline for teenagers
+              base_path: /careers-helpline-for-teenagers
+          topics:
+            - title: Apprenticeships, 14 to 19 education and training for work
+              base_path: /browse/education/find-course
+              document_type: topic
+            - title: Finding a job
+              base_path: /browse/working/finding-job
+              document_type: topic
+            - title: Apprenticeships
+              base_path: /topic/further-education-skills/apprenticeships
+              document_type: topic
+          topical_events:
+            - title: UK-China High-Level People to People Dialogue 2017
+              base_path: /government/topical-events/uk-china-high-level-people-to-people-dialogue-2017
+              document_type: topical_event
+          world_locations:
+            - title: Algeria
+              base_path: /world/algeria/news
+            - title: Austria
+              base_path: /world/austria/news
+            - title: Belarus
+              base_path: /world/belarus/news
+            - title: Belgium
+              base_path: /world/belgium/news
+            - title: Bolivia
+              base_path: /world/bolivia/news
+            - title: Brazil
+              base_path: /world/brazil/news
+            - title: Canada
+              base_path: /world/canada/news
+            - title: Chile
+              base_path: /world/chile/news
+            - title: China
+              base_path: /world/China/news
+ 

data/app/views/govuk_publishing_components/components/docs/share_links.yml

@@ -3,6 +3,8 @@ description: Social media links for linking to or sharing the current page on so
 body: |
   The component will not process a URL into a share link itself. Pass complete share URLs to the component.
 
+  Note that the component automatically appends visually hidden text to the link (default: `Share on <your text> (opens in a new tab)`). Consider this when setting the link text.
+
   Real world examples:
 
     - [News article](https://www.gov.uk/government/news/fast-tracking-uk-innovation-apply-for-business-funding)
@@ -44,36 +46,27 @@ examples:
       ]
     context:
       right_to_left: true
-  track_as_sharing_links:
-    description: Where the component is used to allow users to share content on social media, tracking can be added that uses [Social Interactions](https://developers.google.com/analytics/devguides/collection/analyticsjs/social-interactions) in UA. If this option is not included, it is assumed the component is simply linking to social media pages and the extra options are omitted from the tracking call in UA. In GA4, when this is set to true, a JSON is added to a data-attribute called data-ga4-link, which is detected by ga4-link-tracker.js and pushed to the dataLayer.
-    data:
-      track_as_sharing: true
-      links: [
-        {
-          href: 'share',
-          text: 'Share on Facebook',
-          icon: 'facebook'
-        },
-        {
-          href: 'share',
-          text: 'Share on Twitter',
-          icon: 'twitter'
-        },
-      ]
-  track_as_follow_links:
-    description: Where the component is used to allow users to follow us on social media, tracking can be added. When this is set to true, a JSON is added to a data-attribute called data-ga4-link, which is detected by ga4-link-tracker.js and pushed to the dataLayer.
+  with_data_attributes:
+    description: Data attributes can be added to both the parent element and the individual share links, as shown. Note that the component defaults to having a `data-module` of `gem-track-click`, but this is preserved even if another value for module is passed.
     data:
-      track_as_follow: true
+      data_attributes:
+        module: 'example-passed-module'
       links: [
         {
-          href: 'follow',
-          text: 'Follow us on Facebook',
-          icon: 'facebook'
+          href: '/facebook-share-link',
+          text: 'Facebook',
+          icon: 'facebook',
+          data_attributes: {
+            meeting: 'hello'
+          },
         },
         {
-          href: 'follow',
-          text: 'Follow us on Twitter',
-          icon: 'twitter'
+          href: '/twitter-share-link',
+          text: 'Twitter',
+          icon: 'twitter',
+          data_attributes: {
+            departing: 'goodbye'
+          },
         },
       ]
   with_title:
@@ -83,9 +76,22 @@ examples:
         {
           href: 'share',
           text: 'Share on Facebook',
+          hidden_text: '',
           icon: 'facebook'
         }
       ]
+  with_branding:
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
+    data:
+      brand: 'attorney-generals-office'
+      links: [
+        {
+          href: 'share',
+          text: 'Follow the Attorney General on Twitter',
+          hidden_text: '',
+          icon: 'twitter'
+        }
+      ]      
   with_custom_visually_hidden_text:
     description: |
       Use this option to specify a visually hidden text for screenreaders to prepend to the link text.
@@ -100,16 +106,39 @@ examples:
           icon: 'facebook'
         }
       ]
-  with_branding:
-    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
+  track_as_sharing_links:
+    description: Where the component is used to allow users to share content on social media, tracking can be added that uses [Social Interactions](https://developers.google.com/analytics/devguides/collection/analyticsjs/social-interactions) in UA. If this option is not included, it is assumed the component is simply linking to social media pages and the extra options are omitted from the tracking call in UA. In GA4, when this is set to true, a JSON is added to a data-attribute called data-ga4-link, which is detected by ga4-link-tracker.js and pushed to the dataLayer.
     data:
-      brand: 'attorney-generals-office'
+      track_as_sharing: true
       links: [
         {
           href: 'share',
-          text: 'Follow the Attorney General on Twitter',
+          text: 'Share on Facebook',
+          icon: 'facebook'
+        },
+        {
+          href: 'share',
+          text: 'Share on Twitter',
           icon: 'twitter'
-        }
+        },
+      ]
+  track_as_follow_links:
+    description: Where the component is used to allow users to follow us on social media, tracking can be added. When this is set to true, a JSON is added to a data-attribute called data-ga4-link, which is detected by ga4-link-tracker.js and pushed to the dataLayer.
+    data:
+      track_as_follow: true
+      links: [
+        {
+          href: 'follow',
+          text: 'Follow us on Facebook',
+          hidden_text: '',
+          icon: 'facebook'
+        },
+        {
+          href: 'follow',
+          text: 'Follow us on Twitter',
+          hidden_text: '',
+          icon: 'twitter'
+        },
       ]
   stack_vertically:
     data:

data/app/views/govuk_publishing_components/components/docs/single_page_notification_button.yml

@@ -33,7 +33,8 @@ examples:
       margin_bottom: 5
   with_js_enhancement:
     description: |
-      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.
+      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.
+
     data:
       base_path: '/current-page-path'
       js_enhancement: true
@@ -48,3 +49,17 @@ examples:
       base_path: '/current-page-path'
       js_enhancement: true
       button_location: 'top'
+  with_custom_button_text:
+    description: The component accepts custom button text, provided that both subscribe and unsubscribe text is provided.
+    data:
+      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:
+    description: 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.
+    data:
+      base_path: '/current-page-path'
+      js_enhancement: true
+      skip_account: true