CookieConsent
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.
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.
| 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 common cookies “helConsentCookie” and “helConsentCookieVersion” 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 window.location.hostname. This way, the cookie consents are limited to a single service, which makes the cookie more secure and understandable for the user which cookies are used right here.
If you want to set the domain manually for some reason, then use the cookieDomain property.
If the service domain is the top level hel.fi, use the customDomain property to set the cookie domain to www.hel.fi, or it will be readable by all.
Cookies for domains on the public suffix list cannot accept subdomain cookies. E.g. github.io.
If the cookieDomain is manually changed, there might be a scenario where consents are stored in two domains and two sets of consents are found in the document.cookie. If the component detects two sets of consents, it will remove both. There is no reliable way of knowing which consents are the latest. After the removal, consents will be asked again.
Detailed info about properties
Required and optional cookies
| 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. |
Cookie groups
| 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. |
Cookie information
| 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:
| 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.
| 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. |
| 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. |
| 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.
| 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. A version number indicating which version of the component is in use, is stored to a city-of-helsinki-cookie-consents-version cookie. The version number has no relation to the stored consents.
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.