Single-Page

Customizing the Single Page Account UI

To initialize a Single-Page account theme run the following command:

npx keycloakify initialize-account-theme # Select 'Sigle-Page'

📌 Timestamps: 00:00 – Intro 03:33 – Changing the logo 07:46 – Using a custom button component 14:13 – Update process 16:55 – Translations (i18n) 18:23 – Enabling your account theme in the Keycloak Admin Console

Initialize the Account

After initialization, there will be many files that are part of the theme but are currently git-ignored. To customize a file and ensure it's tracked, run the own command included at the top of the file. For instance, at the top of KcPage.tsx you'll see npx keycloakify own --path "account/KcPage.tsx".

When a new person clones the project and runs the installation script, their project will populate with all the necessary files while continuing to be git-ignored.

Running the Server

To preview the application use npx keycloakify start-keycloak. This will run your application within a Keycloak container. Open the local realm version and select the Account theme link. Once that is open, you'll be able to work like you normally would on any React application with instant refresh and reload.

Note

If you have a Login theme where you are forcing a specific template to render, make sure to comment that out. Otherwise, you will never be able to log in.

Updating the Logo

Own the Header.tsx (src/account/root/Header.tsx) file.
Add your own logo to the Assets (src/account/assets) folder.
Update the logo import to your new logo. import logoSvgUrl from "../assets/logo.svg"; becomes import logoSvgUrl from "../assets/your-logo.svg"; or whatever.
Run the server with npx keycloakify start-keycloak.

Updating a Custom Component

Updating a component that comes from PatternFly, means that we need to create a new component in some fashion. In order to make it possible to edit the components that are used from PatternFly, those are re-exported from the core library of PatternFly.

In the project structure, locate /src/shared/@patternfly/.../index.tsx of whatever component or item you want to edit. Run the own command for that specific file.
For the sake of this example, let's create a "CustomButton" component from the @patternfly/react-core package. Create a new file CustomButton.tsx at the same level as the index file (e.g., /src/shared/@patternfly/react-core/CustomButton.tsx).
Inside that component, you can create it however you want. For example, you could do

import { type ButtonProps, Button } from "@patternfly/react-core";
import { css } from "@patternfly/react-styles";
import styles from "./CustomButton.module.css"; // Import the CSS module

export function CustomButton(props: ButtonProps) {
  const { children, variant = "primary", className: className_props, ...rest } = props;

  const className = css(styles.button, styles[variant], className_props);

  if (variant === "link") {
    return (
      <Button {...rest} className={className} variant="link">
        {children}
      </Button>
    );
  }

  return (
    <button {...rest} className={className}>
      {children}
    </button>
  );
}

You'll notice that it imports a CSS module file. Create CustomButton.module.css right next to it and style however you want.
In the index.tsx file then export the component. This will then override the button exported by Patternfly and apply it to every page that imports that button.

export * from "@patternfly/react-core";
export { CustomButton as Button } from "./CustomButton";

Update Instances

The core module for the account is @keycloakify/keycloak-account-ui. You can always update the minor versions without issues (simply update them and run the installation script).

Translations

Each file has instructions at the top of it. Generally, just create an override file and not own the base translation file. This will help to make sure only those changes take effect.