CSS Customization

This page is a must read, even if you plan on redesinging the pages at the component level you must at least understand how to remove the default CSS styles.

Understanding the CSS class system

Upon inspecting the DOM in storybook you will see that most element have at least a couple of classes applied to them.

• A class starting with kc, for example kcLabelClass.

• One or more classes with pf-, for example pf-c-form__label, pf-c-form__label-text

Inspecting an input label on the login page

The classes starting with kc do not have any actual styles applied to them. Their sole purpose is to be a target for you to apply your custom styles.

The classes with pf- are Paterfly classes. Patternfly is a CSS framwork in the like of Bootstrap created by RedHat, it is what the the Keycloak team uses to build all their UIs.

Applying your custom CSS

Do not edit the any file in the public/keycloakify-dev-resources directory. Thoses are resource files used by Storybook for simulating a Keycloak environement during devloppement, thoses files aren't part of your theme.

To apply your custom CSS style you should use the kc classes to target the components.

src/login/main.css

.kcLabelClass {
   border: 3px solid red;
}

React

src/login/KcApp.tsx

import "./main.css";
// ...

Svelte

src/login/KcPage.svelte

<script lang="ts">
  import "./main.css";
  import Template from '@keycloakify/svelte/login/Template.svelte';
  ...

This will be the result:

A red border has been applied to every input label

Having diferent stylesheet for the login page, the register page ext...

Here we used a global stylesheet that applies to all pages of the login theme however you can also apply stylesheet on a page-by-page basis (a stylesheet for the login page, another stylesheet for the register page ect...).

If you are planning to customize the pages using React/Angular/Svelte at the component level it will be very obvious how to do so after reading the using a component library page.

However if you plan to stick with with CSS only customization it might not be apparent to you how to do it so here is shat show how it can be acheived:

src/login/KcPage.tsx

import {
    Suspense, 
    lazy,
    useMemo
} from "react";

export default function KcPage(props: { kcContext: KcContext }) {
    const { kcContext } = props;

    const { i18n } = useI18n({ kcContext });

    const classes = useCustomStyles(kcContext);

    return (
        <Suspense>
            {(() => {
                switch (kcContext.pageId) {
                    default:
                        return (
                            <DefaultPage
                                kcContext={kcContext}
                                i18n={i18n}
                                classes={classes}
                                Template={Template}
                                doUseDefaultCss={true}
                                UserProfileFormFields={UserProfileFormFields}
                                doMakeUserConfirmPassword={doMakeUserConfirmPassword}
                            />
                        );
                }
            })()}
        </Suspense>
    );
}

function useCustomStyles(kcContext: KcContext) {
    return useMemo(() => {
        
        // You stylesheet that applies to all pages.
        import("./main.css");
        let classes: { [key in ClassKey]?: string } = {
            // Your classes that applies to all pages
        };

        switch (kcContext.pageId) {
            case "login.ftl":
                // You login page specific stylesheet.
                import("./pages/login.css");
                classes = {
                    ...classes,
                    // Your classes that applies only to the login page
                };
                break;
            case "register.ftl":
                // Your account page specific stylesheet
                import("./pages/register.css");
                classes = {
                    ...classes,
                    // Your classes that applies only to the register page
                };
                break;
            // ...
        }

        return classes;

    }, []);
}

If this code does not make much sense to you you can check out this video tutorial where this approach is demonstrated in practice.

Using Tailwind

You'll be of course able to use Tailwind the regular way by applying the utility classes to the React/Angular/Svelte components. However be aware that you can also use tailwind without having to modify the pages structures using the @apply dirrective. It's demonstrated in this page.

Using Bootstrap or some other CSS framwork

If you wish to use bootstrap or some other CSS framwork that provide standardized CSS classes you might wonder how to apply thoses classes. Here is an example with Bootstrap:

yarn add bootstrap

src/login/KcPage.tsx

import "bootstrap/dist/css/bootstrap.min.css";
import { Suspense, lazy } from "react";
import type { ClassKey } from "keycloakify/login";
import type { KcContext } from "./KcContext";
import { useI18n } from "./i18n";
import DefaultPage from "keycloakify/login/DefaultPage";
import Template from "keycloakify/login/Template";
const UserProfileFormFields = lazy(
    () => import("keycloakify/login/UserProfileFormFields")
);

const doMakeUserConfirmPassword = true;

export default function KcPage(props: { kcContext: KcContext }) {
    const { kcContext } = props;

    const { i18n } = useI18n({ kcContext });

    return (
        <Suspense>
            {(() => {
                switch (kcContext.pageId) {
                    default:
                        return (
                            <DefaultPage
                                kcContext={kcContext}
                                i18n={i18n}
                                classes={classes}
                                Template={Template}
                                doUseDefaultCss={true}
                                UserProfileFormFields={UserProfileFormFields}
                                doMakeUserConfirmPassword={doMakeUserConfirmPassword}
                            />
                        );
                }
            })()}
        </Suspense>
    );
}

const classes = {
    kcLabelClass: "form-label col-form-label",
} satisfies { [key in ClassKey]?: string };

By writing that you've effectively replaced the Patterfly classes pf-c-form__label pf-c-form__label-text by the bootstrap classes form-label col-form-label.

dWhat will happen in practice, if you inspect the lement in your browser is that the form label that was previously rendered as:

<label for="username" class="kcLabelClass pf-c-form__label pf-c-form__label-text">

Will is now rendered as

<label for="username" class="kcLabelClass form-label col-form-label">

Removing Some of the Default Styles

Let's consider the "Sign In" button of the login page:

The default look of the "Sign In" button

Let's see how we can unstyle it so that we can apply our custom styles without having to wory about our CSS conflicting with the default Patternlyfly styles.

How the "Sign in" button looks with all the Patterfly styles removed

To remove the Patternfly styles we must first inspect the element in our browser:

Inspecting the CSS classes apllied to the "Sign In" button

Doing that we can see what Patterfly classes are applied by default to the standardized element:

• kcButtonClass get assigned pf-c-button

• kcButtonPrimaryClass get assigned pf-m-primary and long-pf-btn

• kcButtonBlockClass get assigned pf-m-block

• kcButtonLargeClass get assigned btn-lg

Since we want to remove all the default styles we can instruct Keycloakify to remove all the classes that gets assigned by default to thoses kc classes:

src/login/KcPage.tsx

// ...

const classes = {
    kcButtonClass: "",
    kcButtonPrimaryClass: "",
    kcButtonBlockClass: "",
    kcButtonLargeClass: ""
} satisfies { [key in ClassKey]?: string };

After saving this changes this is what we get:

All Patternfly classes have been stripped out, resulting in the button being restored to it's default HTML style.

Now we can freely apply some custom styles to our button without having Patternfly interfering.

Button with custom style

Reveal custom CSS code of this custom button

src/login/main.css

.kcButtonClass {
    padding: 10px 20px;
    font-size: 16px;
    font-weight: bold;
    text-transform: uppercase;
    color: #ffffff;
    background: linear-gradient(45deg, #6a11cb, #2575fc);
    border: none;
    border-radius: 25px;
    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
    transition: transform 0.2s, box-shadow 0.2s;
    cursor: pointer;
    width: 100%;
}

.kcButtonClass:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 8px rgba(0, 0, 0, 0.2);
}

.kcButtonClass:active {
    transform: translateY(0);
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
}

.kcButtonClass:focus {
    outline: none;
    box-shadow: 0 0 0 3px rgba(37, 117, 252, 0.5);
}

Remove All the Default Styles

Maybe you'd prefer to remove all the Patterfly style alltogether and start fresh.

The login page completely unstyled (doUseDefaultCss set to false).

What's nice with this approach is that not only will all the pf classes been stripped out all at once but also the global Patterfly stylesheet won't even be loaded.

React

src/login/KcPages.tsx

// ...
<DefaultPage
    kcContext={kcContext}
    i18n={i18n}
    classes={classes}
    Template={Template}
    doUseDefaultCss={false}
    UserProfileFormFields={UserProfileFormFields}
    doMakeUserConfirmPassword={doMakeUserConfirmPassword}
/>

Svelte

src/login/KcPage.svelte

{#await page() then { default: Page }}
    <Page
      {kcContext}
      i18n={i18n}
      {classes}
      {Template}
      {UserProfileFormFields}
      doUseDefaultCss={false}
      {doMakeUserConfirmPassword}
    ></Page>
{/await}

Angular

src/login/KcPage.ts

const classes = {} satisfies { [key in ClassKey]?: string };
const doUseDefaultCss = false;
const doMakeUserConfirmPassword = true;

export async function getKcPage(pageId: KcContext['pageId']): Promise<KcPage> {
  switch (pageId) {
    default:
      return {
        PageComponent: await getDefaultPageComponent(pageId),
        TemplateComponent,
        UserProfileFormFieldsComponent,
        doMakeUserConfirmPassword,
        doUseDefaultCss,
        classes,
      };
  }
}

Disabeling the default styles only on some page.

A common scenario is to use npx keycloakify eject-page to eject some pages of the login UI to customize them in depth.

On the page that you have ejected, you're likely to want to disable all the default styles, however you might want to keep the Patterfly styles on the pages that you haven't redesigned. Here is an example where the login.ftl page have been ejected, disable the default styles for it while keeping them for the other pages:

React

src/login/KcPages.tsx

switch (kcContext.pageId) {
    case "login.ftl":
        return (
            <Login
                {...{ kcContext, i18n, classes }}
                Template={Template}
                doUseDefaultCss={false}
            />
        );
    default:
        return (
            <DefaultPage
                kcContext={kcContext}
                i18n={i18n}
                classes={classes}
                Template={Template}
                doUseDefaultCss={true}
                UserProfileFormFields={UserProfileFormFields}
                doMakeUserConfirmPassword={doMakeUserConfirmPassword}
            />
        );
}

Angular

src/login/KcPage.ts

  switch (pageId) {
    case 'login.ftl':
      return {
        PageComponent: (await import('./pages/login/login.component')).LoginComponent,
        TemplateComponent,
        UserProfileFormFieldsComponent,
        doMakeUserConfirmPassword,
        doUseDefaultCss: false,
        classes,
      };
    default:
      return {
        PageComponent: await getDefaultPageComponent(pageId),
        TemplateComponent,
        UserProfileFormFieldsComponent,
        doMakeUserConfirmPassword,
        doUseDefaultCss: true,
        classes,
      };
  }

Svelte

src/login/KcPage.svelte

<script lang="ts">
  // ...
  const doUseDefaultCss = (()=>{
    switch(kcContext.pageId){
      case "login.ftl": return false;
      return true;
    }
  })();
  
  const page = async (): Promise<{ default?: Component<any> }> => {
    switch (kcContext.pageId) {
      case 'login.ftl':
        return import('./pages/Login.svelte"');
      default:
        return import('@keycloakify/svelte/login/DefaultPage.svelte');
    }
  };
</script>

{#await page() then { default: Page }}
    <Page
      {kcContext}
      i18n={i18n}
      {classes}
      {Template}
      {UserProfileFormFields}
      {doUseDefaultCss}
      {doMakeUserConfirmPassword}
    ></Page>
{/await}

Removing the classes in the ejected components (kcClsx)

If you have ejected some pages with npx keycloakify eject-page and disabled the defaut styles with doUseDefaultCss set to false you might wonder if you need to keep the kcClsx in the pages, for example:

src/login/pages/Login.tsx

<input
    tabIndex={7}
    disabled={isLoginButtonDisabled}
    className={kcClsx(
        "kcButtonClass", 
        "kcButtonPrimaryClass", 
        "kcButtonBlockClass", 
        "kcButtonLargeClass"
    )}
    name="login"
    id="kc-login"
    type="submit"
    value={msgStr("doLogIn")}
/>

The answer is no, feel free to remove them!

Just be aware that if you have defined some custom CSS that use the kc classes as selector ( Like for example .kcButtonClass { /* ... */ } ) they will no longer be applied.