Customizing UI Text (languageStrings)

Relevant source files

The following files were used as context for generating this wiki page:

• src/modules/GrantsInterface.ts
• README.md
• src/modules/ConsentManager.ts
• src/styles.scss
• src/bundle.ts

The consent-manager library provides ready-to-use UI components, the GrantsInterface, which includes a cookie banner and a preferences modal. The text displayed in these components is fully customizable through the languageStrings configuration object. This allows developers to override the default English text to provide internationalization (i18n) or simply to match the tone and style of their website.

Customization is achieved by passing a languageStrings object during the instantiation of the GrantsInterface class. The provided custom strings are merged with the default configuration, allowing for partial or complete overrides.

Sources: src/modules/GrantsInterface.ts:6-19, README.md:143-161

Configuration

The customization of UI text is handled via the languageStrings property within the GrantsInterface configuration object. This object is passed as the second argument to the GrantsInterface constructor.

Sources: src/modules/GrantsInterface.ts:43-45

Configuration Structure

The languageStrings object is nested within the main GrantsInterfaceConfig and is structured into two main properties: banner and modal, corresponding to the two UI components.

interface GrantsInterfaceConfig {
  autoShow?: boolean;
  languageStrings?: {
    banner?: {
      infoText?: string;
      accept?: string;
      reject?: string;
      options?: string;
    };
    modal?: {
      title?: string;
      accept?: string;
      reject?: string;
    };
  };
}

Sources: src/modules/GrantsInterface.ts:5-19

The following diagram illustrates the structure of the GrantsInterfaceConfig.

Default Values

If no custom languageStrings are provided, the GrantsInterface uses a set of default English strings. When a custom configuration is provided, it is deeply merged with these defaults, meaning you only need to specify the strings you wish to change.

The default configuration is defined as follows:

const defaultConfig: GrantsInterfaceConfig = {
  autoShow: true,
  languageStrings: {
    banner: {
      infoText:
        'This website uses cookies to ensure you get the best experience on our website.',
      accept: 'Accept All',
      reject: 'Only required',
      options: 'More options',
    },
    modal: {
      title: 'Consent options',
      accept: 'Accept All',
      reject: 'Only required',
    },
  },
};

Sources: src/modules/GrantsInterface.ts:21-38

The table below summarizes all customizable strings and their default values.

Component	Key	Default Value	Description
Banner	infoText	'This website uses cookies to ensure you get the best experience on our website.'	The main informational text displayed in the cookie banner.
Banner	accept	'Accept All'	Text for the button that accepts all cookie categories.
Banner	reject	'Only required'	Text for the button that rejects all optional cookie categories.
Banner	options	'More options'	Text for the button that opens the preferences modal.
Modal	title	'Consent options'	The title displayed at the top of the preferences modal.
Modal	accept	'Accept All'	Text for the button in the modal that accepts all categories.
Modal	reject	'Only required'	Text for the button in the modal that rejects optional categories.

Sources: src/modules/GrantsInterface.ts:21-38

Implementation

When a new GrantsInterface object is created, it merges the user-provided configuration with the defaultConfig using a deepmerge utility. The resulting configuration is stored and used to populate the text content of the DOM elements for the banner and modal when they are rendered.

The following sequence diagram shows the process of initializing GrantsInterface with custom strings and displaying the banner.

Usage Example

To customize the UI text, pass a languageStrings object when creating the GrantsInterface instance. You can override any or all of the default strings.

import { GrantsInterface } from 'consent-manager';
import 'consent-manager/dist/consent-manager.css';

// consentManager is an instance of the core ConsentManager
const gi = new GrantsInterface(consentManager, {
  languageStrings: {
    banner: {
      infoText: 'This website uses cookies to ensure you get the best experience on our website.',
      accept: 'Accept All',
      reject: 'Only required',
      options: 'More options'
    },
    modal: {
      title: 'Consent options',
      accept: 'Accept All',
      reject: 'Only required'
    }
  }
});

Sources: README.md:143-161

Customizing the Banner

The banner UI is constructed in the showBanner method. The text for the info span and the three action buttons (Accept, Reject, More options) is pulled directly from the config.languageStrings.banner object.

• infoText is applied to a <span> inside .consent-manager--banner-info.
• accept is applied to the .consent-manager--banner-accept button.
• reject is applied to the .consent-manager--banner-reject button.
• options is applied to the .consent-manager--banner-more button.

Sources: src/modules/GrantsInterface.ts:59-86, src/styles.scss:1-39

Customizing the Modal

Similarly, the preferences modal, created by showModal, uses strings from config.languageStrings.modal.

• title is applied to the <h2> with the class .consent-manager--modal-title.
• accept is applied to the .consent-manager--modal-accept button.
• reject is applied to the .consent-manager--modal-reject button.

Sources: src/modules/GrantsInterface.ts:188-190, src/modules/GrantsInterface.ts:211-224, src/styles.scss:75-86, src/styles.scss:91-109