How to install

Note

The following installation instructions have been split up depending on how you use Blazor.

• If you use .NET 8 (or higher) Blazor WebApps AND have your <Router> statically rendered (this means the router's or it's parent component rendermode is not explicitly set for example through [RenderModeWebAssembly] or [RenderModeServer]), then follow the first guide.

• If you use .NET 8 (or higher) Blazor WebApps AND have your <Router> dynamically rendered (this means the router's or it's parent component rendermode is explicitly set for example through [RenderModeWebAssembly] or [RenderModeServer]), then follow the second guide.

• If you use .NET 7 or prior, then follow the third guide.

Localization

For now, localization is done entirely inside the configuration of the services as seen in the example above. The library ships with default texts in English, German Dutch, French and Spanish.

The library uses the current CurrentCulture by default. Blazor's .AddLocalization(..) will automatically set the current culture. We aim at adding proper support for IStringLocalizer aswell, so that all localization can be done inside resource files instead.

Disabled or blocked JavaScript

The library depends on JavaScript to save and load preferences and to enable HTML script tags. If JavaScript is blocked or not enabled by a browser, the library will not be able to dynamically enable JavaScript tags like <script type="text/plain" data-consent-category="myCategoryName">; They will remain disabled even if given permission by the user. Saving and loading preferences will also not be possible, which means any permissions the user has given will be forgotten if the browser tab is closed and are only valid within the browser tab they were given in.

Customizing colors and font

The default consent prompt and settings modal are customizable to some degree with CSS variables.

Use a CSS rule as follows to overwrite colors and font used. The values shown are the current default values as shown in the screenshots using Tailwind's theme function.

.cc-isolation-container * {
    /* Font used */
    --cc-font-family: Inter var, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";

    /* Accent color for primary button */
    --cc-color-accent: theme(colors.slate.800);

    /* Accent color for primary button when hovered */
    --cc-color-accent-dark: theme(colors.slate.900);

    /* Color for secondary button */
    --cc-color-secondary: theme(colors.gray.200);

    /* Color for secondary button when hovered */
    --cc-color-secondary-dark: theme(colors.gray.300);

    /* Color for links ("Display policy" links within preferences dialogue) */
    --cc-color-link: theme(colors.slate.400);

    /* Color for link when hovered */
    --cc-color-link-highlight: theme(colors.blue.500);

    /* Default color for text */
    --cc-color-text: theme(colors.slate.700);

    /* Background color for active category switch */
    --cc-color-switch-active: theme(colors.slate.800);

    /* (Transparent) Color for background when any modal is opened */
    --cc-color-modal-background: theme(colors.gray.800 / 75%);
}

Custom consent prompt and settings modal

You can entirely replace the components that display to ask the user for consent and the settings modal.

First, create a component that inherits from CookieConsentSettingsModalComponentBase/CookieConsentPromptComponentBase.

Then, you must register this component type in the cookie library by creating a custom variant that inherits from CookieConsentPromptVariantBase/CookieConsentPreferencesVariantBase. For example

public class CustomSettingsModalVariant : CookieConsentDefaultSettingsModalVariant
{
    public override Type ComponentType { get; set; } = typeof(YOUR_CUSTOM_COMPONENT);
}

Lastly, you need to register this variant in the AddCookieConsent call.

builder.Services.AddCookieConsent(options =>
{
    // To replace the consent prompt
    options.ConsentPromptVariant = new CustomConsentPromptVariant();

    // To replace the settings modal
    options.SettingsModalVariant = new CustomSettingsModalVariant();

    // ...
});

Available ways to hide/show content based on cookie preferences

JavaScript tags

If you wish to use services like Google Analytics, you can integrate them with this library the following way. This will make it so the script tags do not get run unless allowed to do so by the user.

1. Change the script tags type attribute from type="text/javascript" to type"text/plain".
2. Add the attribute data-consent-category="IDENTIFIER".
3. Replace IDENTIFIER with the Identifier given to a configured category. In the example given earlier, this could be google.

Blazor Server Important note: It appears as though when using Blazor Server, Javascript-tags require the defer="true" attribute to be set so that the script tag is not removed by Blazor upon load (view issue).

The result should look like so:

<script type="text/plain" data-consent-category="google">
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

    ga('create', 'UA-XXXXX-Y', 'auto');
    ga('send', 'pageview');
</script>

This Google Analytics script will only load if given permission.

CookieConsentCheck component

You can use the prebuilt component to show content only if given permission in a category. This can be useful for displaying iframes, for example Google Maps or YouTube videos:

<CookieConsentCheck RequiredCategory="google">
    <Allowed>
        <iframe loading="lazy" allowfullscreen src="https://www.google.com/maps/embed/v1/place?q=place_id:ChIJAVkDPzdOqEcRcDteW0YgIQQ&key=..."></iframe>
    </Allowed>
</CookieConsentCheck>

You can customize what this component will render when the given RequiredCategory is not allowed by defining a NotAllowed tag. By default, the component will render this:

Defining something custom to render can be done the following way. It's a good idea to set the Context parameter on the CookieConsentCheck component so you can easily access it's properties inside your custom NotAllowed block (for example the Component.Category property to access the display name of the required category).

<CookieConsentCheck RequiredCategory="google" Context="Component">
    <Allowed>
        <h1>It works!</h1>
    </Allowed>
    <NotAllowed>
        <button @onclick="async () => await Component.AcceptRequiredAsync()">Show it!</button>
    </NotAllowed>
</CookieConsentCheck>

Manually open the preferences modal

Call the following method to show the preferences menu. This could be done from an element inside your footer for example.

ℹ️ In Blazor Web App, this can be done from both WASM and the Server.

CookieConsentService.ShowSettingsModalAsync();

Stop scripts (like Google Analytics) from running if consent is revoked

If you integrate services such as Google Analytics and the user grants consent, scripts might start running in the background. To stop these scripts from executing once the user revokes consent, it is necessary to refresh the page.

To achieve this, you can subscribe to the following event and evaluate whether a specific category consent has been revoked that requires action such as refreshing the page to stop aforementioned scripts:

CookieConsentService.CategoryConsentChanged += (sender, args) =>
{
    if (args.CategoryIdentifier == "google" &&
        args.ChangedTo == ConsentChangedArgs.ConsentChangeType.Revoked &&
        !args.IsInitialChange)
    {
        // Reload the current page with a hard refresh (restart Blazor app).
        NavigationManager.NavigateTo(NavigationManager.Uri, forceLoad: true);
    }
};

Check for the cookie consent state in non-interactive Blazor components such as statically rendered Blazor components, Razor pages or controllers

To accomplish this, you need to read the contents of the cookie which contains the cookie consent preferences encoded in Base64.

The easiest way to achieve this is to use the helper package:

Install-Package BytexDigital.Blazor.Components.CookieConsent.AspNetCore

After installation, add the following service registration:

builder.Services.AddCookieConsentHttpContextServices();

Then request the service from the service container, e.g. in a static Blazor component:

[Inject]
public HttpContextCookieConsent CookieConsent { get; set; }

You can then use the service to fetch the CookiePreferences object.

var preferences = CookieConsent.GetCookieConsentPreferences();

bool isAllowed = preferences.IsCategoryAllowed("google");

Checking for scripts to be loaded before interacting with them or rendering content

Sometimes your code may depend on <script> tags having run, which might be dependant on whether their consent category has been enabled by the user (see #javascript-tags). To make your code run when these script tags are enabled, you might try to listen to the CookieConsentService.CategoryConsentChanged and execute your code if the category of these scripts is enabled. However, inside this event handler, it is not guaranteed that the scripts, enabled by the category you're waiting for, have already run and are ready for usage.

To avoid this race condition, you should additionally use CookieConsentService.ScriptLoaded and CookieConsentService.GetLoadedScriptsAsync to determine if a script you need has already been fully loaded and executed in the DOM.

As an example, let's use the Google Maps API. This example assumes you've setup a cookie consent category with the ID google.

First, you need to add the JS script tag to the Google Maps API library into your host file as follows. Pay attention to how we're giving this script tag a special ID to recognize it by, in this case it's google-maps-api.

<script data-consent-category="google"
        data-consent-script-id="google-maps-api"
        src="https://maps.googleapis.com/maps/api/js?key=YOURKEY&v=3" type="text/plain">
</script>

Now, there are two ways you can go about checking if this script is loaded in the browser. One utilizes the CookieConsentService.ScriptLoaded and CookieConsentService.GetLoadedScriptsAsync methods to achieve this, the other utilizes the ready-built component CookieConsentScriptsLoadedCheck which may be usable for you in some scenarios.

Changelog

1.2.0

• Adds event CookieConsentService.ScriptLoaded to execute code when script tags have been loaded dynamically by the cookie consent manager
• Adds component CookieConsentScriptsLoadedCheck that can be used to conditionally render content depending on whether scripts have been loaded by the cookie consent manager

1.1.0

• Support for .NET 8 Blazor Web Apps with mixed WebAssembly and Server usage
• The settings/preferences modal is now replaceable just like the consent prompt is
• Various internal improvements

1.0.18

1.0.17

1.0.16

1.0.15

1.0.13

1.0.12

1.0.11

1.0.10

1.0.9

1.0.6