keycloak-scim/docbook/reference/en/en-US/modules/themes.xml

<chapter id="themes">
    <title>Themes</title>

    <para>
        Keycloak provides theme support for login forms and account management. This allows customizing the look
        and feel of end-user facing pages so they can be integrated with your brand and applications.
    </para>

    <section>
        <title>Configure theme</title>
        <para>
            To configure the theme used by a realm open the <literal>Keycloak Admin Console</literal>, select your realm
            from the drop-down box in the top left corner. In the <literal>Optional Settings</literal> use the drop-down
            boxes for <literal>Login Theme</literal> and <literal>Account Theme</literal> to select the theme used
            by login forms and account management pages.
        </para>
    </section>

    <section>
        <title>Default themes</title>
        <para>
            Keycloak comes bundled with default themes in <literal>standalone/configuration/themes</literal>. It is
            not recommended to edit these themes directly. Instead you should create a new theme to extend a default
            theme. A good reference is to copy the keycloak themes as these extend the base theme to add styling.
        </para>
    </section>

    <section>
        <title>Creating a theme</title>
        <para>
            There are several types of themes in Keycloak:
            <itemizedlist>
                <listitem>Account - Account management</listitem>
                <listitem>Admin - Admin console</listitem>
                <listitem>Common - Shared resources for themes</listitem>
                <listitem>Email - Emails</listitem>
                <listitem>Login - Login forms</listitem>
            </itemizedlist>
        </para>

        <para>
            A theme consists of:
            <itemizedlist>
                <listitem><para><ulink url="http://freemarker.org">FreeMarker</ulink> templates</para></listitem>
                <listitem><para>Stylesheets</para></listitem>
                <listitem><para>Scripts</para></listitem>
                <listitem><para>Images</para></listitem>
                <listitem><para>Message bundles</para></listitem>
                <listitem><para>Theme properties</para></listitem>
            </itemizedlist>
        </para>
        <para>
            A theme can extend another theme. When extending a theme you can override individual files (templates, stylesheets, etc.).
            The recommended way to create a theme is to extend the base theme. The base theme provides templates
            and a default message bundle. It should be possible to achieve the customization required by styling these
            templates.
        </para>
        <para>
            To create a new theme, create a folder in <literal>.../standalone/configuration/themes/&lt; theme type&gt;</literal>.
            The name of the folder is the name of the theme. Then create a file <literal>theme.properties</literal> inside the theme folder.
            The contents of the file should be:
        </para>
        <programlisting>parent=base</programlisting>
        <para>
            You have now created your theme. Check that it works by configuring it for a realm. It should look the same
            as the base theme as you've not added anything to it yet. The next sections will describe how to modify
            the theme.</para>
        <section>
            <title>Stylesheets</title>
            <para>
                A theme can have one or more stylesheets, to add a stylesheet create a file inside <literal>resources/css</literal> (for example <literal>resources/css/styles.css</literal>)
                inside your theme folder. Then registering it in <literal>theme.properties</literal> by adding:
            </para>
            <programlisting>styles=css/styles.css</programlisting>
            <para>
                The <literal>styles</literal> property supports a space separated list so you can add as many
                as you want. For example:
            </para>
            <programlisting>styles=css/styles.css css/more-styles.css</programlisting>
        </section>
        <section>
            <para>
                A theme can have one or more scripts, to add a script create a file inside <literal>resources/js</literal> (for example <literal>resources/js/script.js</literal>)
                inside your theme folder. Then registering it in <literal>theme.properties</literal> by adding:
            </para>
            <programlisting>scripts=js/script.js</programlisting>
            <para>
                The <literal>scripts</literal> property supports a space separated list so you can add as many
                as you want. For example:
            </para>
            <programlisting>scripts=js/script.js js/more-script.js</programlisting>
        </section>
        <section>
            <title>Images</title>
            <para>
                To make images available to the theme add them to <literal>resources/img</literal>. They can then be used
                through stylesheets. For example:
            </para>
            <programlisting>body {
    background-image: url('../img/image.jpg');
}</programlisting>
            <para>
                Or in templates, for example:
            </para>
            <programlisting>&lt;img src="${url.resourcesPath}/img/image.jpg"&gt;</programlisting>
        </section>
        <section>
            <title>Messages</title>
            <para>
                Text in the templates are loaded from message bundles. Currently internationalization isn't supported,
                but that will be added in a later release. A theme that extends another theme will inherit all messages
                from the parents message bundle, but can override individual messages. For example to replace
                <literal>Username</literal> on the login form with <literal>Your Username</literal> create the file
                <literal>messages/messages.properties</literal> inside your theme folder and add the following content:
            </para>
            <programlisting>username=Your Username</programlisting>
        </section>
        <section>
            <title>Modifying HTML</title>
            <para>
                Keycloak uses <ulink url="http://freemarker.org">Freemarker Templates</ulink> in order to generate HTML.
                These templates are defined in <literal>.ftl</literal> files and can be overriden from the base theme.
                Check out the Freemarker website on how to form a template file.
            </para>
        </section>
    </section>

    <section>
        <title>SPIs</title>
        <para>
            For full control of login forms and account management Keycloak provides a number of SPIs.
        </para>
        <section>
            <title>Theme SPI</title>
            <para>
                The Theme SPI allows creating different mechanisms to providing themes for the default FreeMarker based
                implementations of login forms and account management. To create a theme provider you will need to implement
                <literal>org.keycloak.freemarker.ThemeProvider</literal> and <literal>org.keycloak.freemarker.Theme</literal> in
                <literal>forms/common-freemarker</literal>.
            </para>
            <para>
                Keycloak comes with two theme providers, one that loads themes from the classpath (used by default themes)
                and another that loads themes from a folder (used by custom themes). Looking at these
                would be a good place to start to create your own theme provider. You can find them inside
                <literal>forms/common-themes</literal> on GitHub or the source download.
            </para>
        </section>
        <section>
            <title>Account SPI</title>
            <para>
                The Account SPI allows implementing the account management pages using whatever web framework or templating
                engine you want. To create an Account provider implement <literal>org.keycloak.account.AccountProviderFactory</literal>
                and <literal>org.keycloak.account.AccountProvider</literal> in <literal>forms/account-api</literal>.
            </para>
            <para>
                Keycloaks default account management provider is built on the FreeMarker template engine (<literal>forms/account-freemarker</literal>).
                To make sure your provider is loaded you will either need to delete <literal>standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-account-freemarker-&project.version;.jar</literal>
                or disable it with the system property <literal>org.keycloak.account.freemarker.FreeMarkerAccountProviderFactory</literal>.
            </para>
        </section>
        <section>
            <title>Login SPI</title>
            <para>
                The Login SPI allows implementing the login forms using whatever web framework or templating
                engine you want. To create a Login forms provider implement <literal>org.keycloak.login.LoginFormsProviderFactory</literal>
                and <literal>org.keycloak.login.LoginFormsProvider</literal> in <literal>forms/login-api</literal>.
            </para>
            <para>
                Keycloaks default login forms provider is built on the FreeMarker template engine (<literal>forms/login-freemarker</literal>).
                To make sure your provider is loaded you will either need to delete <literal>standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-login-freemarker-&project.version;.jar</literal>
                or disable it with the system property <literal>org.keycloak.login.freemarker.FreeMarkerLoginFormsProviderFactory</literal>.
            </para>
        </section>
    </section>

</chapter>