CookieConsent

DraftAccessible

The cookie compliance component informs users about cookie usage. This banner is shown when they visit a website or an application for the first time.

Usage
Code
API
Accessibility

API

Component properties

Common texts, groups and cookie data can be found in HDS-provided content file. The file contains all user interface strings, language options, descriptions for common cookie groups, and details about common Helsinki cookies. By default, this content file is used. You can also override parts of it and add your project-specific groups and cookies.

ContentSource

The contentSource property lists all content, language options, and callbacks for the component. The given source is merged with the default values from the content file to create a content-object.

**Table 1**: ContentSource object properties
Property	Required	Description
`siteName`	Yes	Cookie consent main heading.
`currentLanguage`	Yes	Currently selected language. Used for picking translations from the content file. Is also set to `content.language.current`. Supported values are `fi`, `sv`, and `en`.
`requiredCookies`	No	Required cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: Required and optional cookies.
`optionalCookies`	No	Optional cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: Required and optional cookies.
`requiredCookies.groups`, `optionalCookies.groups`	No	List of cookie groups. All cookies must belong to a group. Groups with the property `commonGroup` will be auto-filled from the content file.
`requiredCookies.groups[].cookies`, `requiredCookies.cookies`, `optionalCookies.groups[].cookies`, `optionalCookies.cookies`	No	List of individual cookies. All cookies must belong to a group or they must have property `commonGroup` or `groupId`. The `groupId` must match `group.id` of a custom group and the `commonGroup` must match groups in the content file. Do not give both.
`texts`	No	User interface string overrides. By default, strings are fetched from the content file and this object overrides one or multiple texts.
`language`	No	Overrides for default language options. By default, options are fetched from the content file and this object overrides one or more properties. `onLanguageChange` callback is also added here.
`onAllConsentsGiven`	No	See Callbacks section below.
`onConsentsParsed`	No	See Callbacks section below.
`noCommonConsentCookie`	No	Consents are saved to a cookie and this option can prevent showing that cookie in the list of consents. If this is not true, `requiredConsents` are always shown and a common group “sharedConsents” is added to it and also a common cookie “helConsentCookie” to that group. All content for those is in the content file.
`focusTargetSelector`	No	When the modal is closed or the ESC key is pressed when it is open, the focus must be shifted outside the modal. This defines the element to set focus to with this selector (string). Not needed when modal is not used. Throws an error is not set for modal.

ContentSource examples

You can find examples of ContentSource property contents in the HDS CookieConsent Storybook examples.

CookieDomain

The cookie domain is automatically detected from the site the component is on. By default, the component sets the cookie domain to be the root domain with *. This way the cookie consents can be read from all subdomains. For example *.hel.fi.

If your site domain is included in the public suffix list or you do not wish to expose your cookies to subdomains, or you want to set the domain manually for some reason, then use the cookieDomain property.

Cookies for domains on the public suffix list cannot accept subdomain cookies. E.g. github.io.

Detailed info about properties

Required and optional cookies

**Table 2**: Cookie category properties
Property	Description
`requiredCookies`	List of required consents and their descriptions.
`optionalCookies`	List of optional consents and their descriptions.
`*.title`	Title for the consent group. Optional.
`*.text`	Description for the consent group. Optional.
`*.checkboxAriaDescription`	Aria description of the checkbox shown with the category. Optional.
`*.groups`	Optional list of groups. More info is below: Cookie groups.
`*.cookies`	Optional list of cookies. More info is below: Cookie information.

**Table 3**: Cookie group properties
Property	Description
`group[].groupId` / `group[].commonGroup`	Both optional. If a common group is used, then the `commonGroup`. If this is a custom group provide an `groupId`. Not required, if there are no cookies that have a `groupId` set.
`group[].title`	Only for custom groups. Title of the group. Cannot be set for a common group. Must be unique.
`group[].text`	Only for custom groups. Cannot be set for a common group. Description of the group.
`group[].expandAriaLabel`	Only for custom groups. Cannot be set for a common group. Aria-label for the button to show more details of the group.
`group[].checkboxAriaDescription`	Only for custom groups. Cannot be set for a common group. Aria-description for the checkbox for giving consent for all cookies in the group
`group[].cookies`	Optional list of cookies in this group.

**Table 4**: Cookie information properties
Property	Description
`cookie[].groupId` / `cookie[].commonGroup`	The group this cookie belongs to. Optional. Not needed when the cookie is defined in an `optionalCookies` / `requiredCookies.group` If `commonGroup` is used and the group itself is not listed, it is auto-added from the content file.
`cookie[].commonCookie`	Optional. Use when the cookie is common.
`cookie[].id`	The ID of the consent. This ID is saved in the consent cookie. Must be unique. Only for custom cookies. Cannot be set for a common cookie.
`cookie[].name`	Readable cookie name. Only for custom cookies. Cannot be set for a common cookie.
`cookie[].hostName`	Hostname where it is used. Only for custom cookies. Cannot be set for a common cookie.
`cookie[].description`	Cookie usage description. Only for custom cookies. Cannot be set for a common cookie.
`cookie[].expiration`	When does the cookie expire. Only for custom cookies. Cannot be set for a common cookie.

Callbacks

The contentSource object passed to the component can also include callback functions:

**Table 5**: Component object callbacks
Property	Usage	Arguments
`onAllConsentsGiven`	Called when the user has given all consents. Not called if consents are not asked for.	Object with `cookie.id` as the key and true/false as value `{matomo: true, marketing: false}`
`onConsentsParsed`	Called when cookie consents are read from the browser, before the cookie modal will possibly be shown. Called always even if consent has been given. Called only once. If content source changes, for example on language change, the callback is called again.	Object with `cookie.id` as the key and true/false as value `{matomo: true, marketing: false}` and boolean indicating are all consents handled. If true, the modal will not be shown.

Strings and language

The following strings can be overridden if needed. Note that you also need to provide translations if you override these. It is recommended to use the provided strings.

**Table 6**: Main text content overrides
Property	Description
`texts.sections.main.title`	Top level heading.
`texts.sections.main.text`	Main description. The most common override because this is service-specific.
`texts.sections.details.title`	Heading shown in the details. Seen when settings are opened.
`texts.sections.details.text`	Description shown in the details. Seen when settings are opened.

**Table 7**: User interface string overrides
Property	Description
`ui.showSettings`	Text on the show/hide settings -button when settings are hidden.
`ui.hideSettings`	Text on the show/hide settings -button when settings are shown.
`ui.approveAllConsents`	Button text for giving consent to all cookies. Shown when settings are closed and the user cannot give optional consents.
`ui.approveRequiredAndSelectedConsents`	Button text for giving consent to required cookies and selected cookies. Shown when settings are open.
`ui.approveOnlyRequiredConsents`	Button text for giving consent to only to required cookies. All optional cookie consents are revoked.
`ui.readMore`	Text shown on a button when modal loses focus and is shrunk.

**Table 8**: Table heading string overrides
Property	Description
`tableHeadings.name`	Title of the “name” column in the cookie description.
`tableHeadings.hostName`	Title of the “hostName” column in the cookie description.
`tableHeadings.description`	Title of the “description” column in the cookie description.
`tableHeadings.expiration`	Title of the “expiration” column in the cookie description.

The consent banner language is controlled via a language dropdown element. Note that the current language is passed in as content.currentLanguage and that value is stored into language.current.

**Table 9**: Language properties
Property	Description
`language.languageOptions`	List of selectable languages. Format: `[{ code: 'fi', label: 'Suomeksi (FI)' }]`
`language.current`	Current language.
`language.languageSelectorAriaLabel`	Aria-label for the language selector button.
`language.onLanguageChange`	Callback called when a new language is selected. Called with new language.code as the argument.

Saving consents

Consents that the user has given are saved to a city-of-helsinki-cookie-consents cookie.

Cookies are always strings and consents are stored as a JSON-formatted string such as {"cookie-id":"true","another-cookie-id":"false"}.

The ID of the cookie is stored as cookie.id. True means the user has given consent for that cookie. All required cookies are always stored true, but other sites may list a common cookie optional, so the stored consent is not true by default.