Custom Css

You can add custom CSS to further customize the look of authentik. Some areas where custom CSS can be applied include:

The flow executor (login and enrollment pages)
The user library and its application cards

:::warning Advanced topic

Custom CSS is an advanced feature. Improper use may lead to unexpected behavior or visual issues. Test changes in a safe environment before applying them to production.

:::

Concepts¶

authentik's design system rests on a few concepts that keep styling consistent across the interface. Understanding them helps when writing custom CSS.

Web components¶

authentik's interface is built using Lit web components (also known as custom HTML elements). Lit is a lightweight library that serves as the foundation of authentik's front-end architecture. Each component encapsulates its own structure, styles, and behavior, enabling modular and reusable UI elements.

authentik's base stylesheet includes CSS styles and variables that ensure a consistent look across all components. Many web components also define their own styles, which can override or extend the base styles. Style encapsulation is a key feature of web components: styles defined within a component don't leak out to affect other parts of the application, and external styles don't affect the component's internals.

Despite this encapsulation, many authentik web components are designed with theming in mind, exposing specific CSS parts and variables that you can target for customization.

CSS variables¶

CSS variables (also called CSS custom properties) define colors, spacing, typography, and other design elements throughout authentik. By overriding these variables in your custom CSS, you can change the interface's look and feel at a high level without targeting individual elements.

Start with authentik's semantic --ak-* variables. They are shorter and more stable than the underlying PatternFly compatibility variables. PatternFly variables remain available for advanced overrides, but --pf-* names are implementation details and may change as authentik's UI evolves.

Common semantic variables include:

Variable	Purpose
`--ak-color-accent`	authentik brand accent
`--ak-color-primary`	primary action and highlight color
`--ak-color-text`	default text color
`--ak-color-text-muted`	secondary text color
`--ak-color-link`	link color
`--ak-color-surface`	default component surface
`--ak-color-surface-muted`	page or muted surface
`--ak-color-border`	default border color
`--ak-color-info`	informational state
`--ak-color-success`	success state
`--ak-color-warning`	warning state
`--ak-color-danger`	danger or destructive state
`--ak-space-md`	default spacing unit
`--ak-radius-sm`	default small radius
`--ak-shadow-md`	default drop shadow for cards and panels
`--ak-shadow-lg`	shadow for popovers and dropdowns
`--ak-font-weight-bold`	bold text weight
`--ak-z-index-lg`	z-index for popovers and dropdowns
`--ak-z-index-xl`	z-index for modal dialogs
`--ak-duration-normal`	default transition duration

authentik currently bridges these semantic variables into selected PatternFly 4 variables. For example, changing --ak-color-primary also affects many PatternFly-backed buttons, links, and highlights.

CSS parts¶

The ::part selector and part attribute allow web components to expose specific elements within their shadow DOM for external styling. This provides a controlled way to customize component appearance without breaking encapsulation.

When customizing authentik, start by modifying CSS variables to achieve broad changes. If you need finer control, use the ::part selector to target specific component parts.

Modes of appearance¶

Color scheme¶

A color scheme preference is a user-agent-provided hint indicating light or dark mode. The browser's color scheme can influence how certain built-in elements render, such as form controls and scrollbars. When no preference is set, authentik typically defaults to light mode.

Theme¶

A theme is a higher-order concept encompassing the overall look and feel of authentik, composed of CSS variables, CSS parts, and other styling rules. A theme should also accommodate user preferences and system settings, such as light or dark mode.

When customizing authentik's appearance, think of the theme as the primary way to define the visual experience rather than targeting individual elements directly.

Viewport considerations¶

When customizing styles that depend on viewport size, use responsive design principles. In authentik's design system, this means using CSS variables that adapt to viewport size rather than hardcoding styles for specific breakpoints.

❌ Static units

ak-library::part(card-header-icon) {
    font-size: 24px;
    margin-bottom: 16px;
}

✅ Responsive units

ak-library::part(card-header-icon) {
    font-size: 2rem;
    margin-block-end: var(--ak-space-md);
}

Many interface elements are aware of their container size and adjust their layout accordingly. Test your customizations across different viewport sizes (mobile, tablet, and desktop).

Accessibility¶

Users may have accessibility preferences set in their operating system or browser, such as high contrast mode or reduced motion. authentik's base theme respects these preferences to ensure a good experience for all users. Keep accessibility in mind so your customizations remain usable regardless of accessibility settings.

User agent hints¶

authentik's interface uses web standards APIs to detect user agent hints and determine the preferred visual experience. Where possible, authentik prioritizes system or browser-level preferences.

However, authentik also applies its own theming rules, so the result stays consistent while still respecting user preferences.

For example:

❌ Direct styling

body {
    background-color: white;
    color: black;
}

@media (prefers-color-scheme: dark) {
    body {
        background-color: black;
        color: white;
    }
}

This directly styles the body element based on the color scheme preference. While this works in simple scenarios, it leads to inconsistencies and maintenance challenges as the application evolves. Compare this with a theme-based approach:

✅ Theme-based styling

:root {
    --ak-color-text: black;
    --ak-color-surface: white;
}

html[data-theme="dark"] {
    --ak-color-text: white;
    --ak-color-surface: black;
}

body {
    background-color: var(--ak-color-surface);
    color: var(--ak-color-text);
}

Here, CSS variables define colors and backgrounds, with values adjusted based on the theme. This approach is more modular and maintainable. Theme changes happen in one place, without editing individual element styles across the application.

Prefer the semantic authentik variables for custom themes:

Custom brand colors

:root {
    --ak-color-accent: #e11d48;
    --ak-color-primary: #2563eb;
    --ak-color-link: #1d4ed8;
    --ak-color-surface: #ffffff;
    --ak-color-surface-muted: #f8fafc;
    --ak-color-text: #0f172a;
    --ak-color-border: #cbd5e1;
}

html[data-theme="dark"] {
    --ak-color-primary: #60a5fa;
    --ak-color-link: #93c5fd;
    --ak-color-surface: #111827;
    --ak-color-surface-muted: #030712;
    --ak-color-text: #f9fafb;
    --ak-color-border: #374151;
}

Contrast ratios (`prefers-contrast`)¶

The Web Content Accessibility Guidelines (WCAG) recommend minimum contrast ratios between text and background colors.

User agents may adjust color rendering to meet these guidelines based on accessibility settings. The prefers-contrast media feature detects user preferences for increased or decreased contrast.

When customizing styles, modify CSS variables before targeting specific elements. Keep in mind that users may prefer either less or more contrast, so avoid hardcoding high-contrast styles that could conflict with their preferences.

Transparency (`prefers-reduced-transparency`)¶

User agents may adjust transparent elements to ensure sufficient visibility based on accessibility settings. The prefers-reduced-transparency media feature detects user preferences for reduced transparency effects.

When customizing styles involving transparency, consider baking transparency effects into your color choices rather than relying on CSS opacity or alpha values.

Motion (`prefers-reduced-motion`)¶

User agents may reduce or eliminate animations and transitions. The prefers-reduced-motion media feature detects user preferences for reduced motion.

A preference for reduced motion doesn't necessarily mean eliminating all motion. Animations that indicate state changes or provide important context may still be appropriate.

Localization (`html[lang]`)¶

The authentik interface supports multiple languages and regional settings. Depending on the detected locale and your instance's localization settings, the interface may adjust text direction (left-to-right or right-to-left), date formats, and other locale-specific elements.

Your custom CSS can accommodate these variations using the [lang] attribute selector:

Changing font for Japanese locale

html[lang="ja"],
html[lang^="ja-"] {
    --ak-font-family-sans-serif:
        "M PLUS 2", "Noto Sans JP", "Hiragino Kaku Gothic Pro", "ヒラギノ角ゴ Pro W3", メイリオ,
        Meiryo, "ＭＳ Ｐゴシック", var(--ak-generic-sans-serif);
}

Examples¶

Enforce a specific color scheme¶

You can enforce a specific color scheme in the Admin interface by navigating to System > Brands and clicking Edit for a brand. Expand Other global settings and modify the Attributes field with the following YAML:

Default a brand to dark mode

settings:
    theme:
        base: dark

To enforce a theme for a specific user, navigate to Directory > Users, click the Edit icon for a user, and modify the Attributes field:

Default a user to light mode

settings:
    theme:
        base: light

:::warning Accessibility consideration

authentik's base theme prioritizes accessibility and may adjust colors and styles based on user preferences or system settings. The browser or operating system may also override the enforced theme to respect user accessibility settings, such as high contrast mode.

Think carefully before enforcing a specific color scheme, as it may conflict with the user's accessibility needs. Overriding accessibility settings may also have legal implications under accessibility laws and regulations in certain jurisdictions.

:::

Hide the locale selector¶

Use this when a brand should use a fixed language and users do not need to select another language on authentication flows.

ak-flow-executor::part(locale-select) {
    display: none;
}

Troubleshooting¶

Custom CSS can be powerful, but it can also lead to unexpected results if not implemented carefully. Here are some common issues and solutions.

My custom CSS is being overridden by authentik's base styles¶

Ensure your CSS selectors are specific enough to override the base styles. You may need to increase specificity or use !important sparingly.
Use browser developer tools to inspect elements and see which styles are being applied and where they come from.

The element you're trying to style may be within a web component's shadow DOM, making it harder to target. Use the ::part selector to target exposed parts of the component. If the element is nested within another web component, the part must be exported by the parent component to be accessible.

Do I have to use CSS parts and CSS variables?¶

authentik doesn't require CSS parts or CSS variables. You can use standard CSS selectors to target elements directly. However, direct element styling is more prone to breaking with updates, as internal structures may change without notice.

:::danger Your custom CSS may break after upgrading authentik

Direct element styling tends to break when authentik updates, since internal structures can change without notice, especially for complex pages like the flow executor. CSS parts are more limited in scope but provide a stable theming API and a more predictable upgrade experience.

:::

Custom CSS doesn't seem to be working at all¶

View your authentik instance in a private or incognito browser window to rule out caching issues.
Ensure your CSS is correctly formatted and free of syntax errors.
Confirm that no runtime errors appear in the browser's developer console that might prevent CSS from being applied.
Verify that the CSS appears in the page's source code using browser developer tools.

If you're still having trouble, the issue may stem from your CDN or reverse proxy caching old versions of your page. Your brand may also not be applicable for the domain you're accessing.

Where can I find documentation on available CSS Variables and Parts?¶

authentik's public semantic variables are documented in the CSS variables section above. You can inspect the rendered HTML using browser developer tools to identify additional component-local CSS variables and parts applied to various elements.

Prefer top-level semantic variables such as --ak-color-primary. Treat --ak-c-* and --pf-* variables as lower-level escape hatches unless a specific authentik release documents them as stable. HTML elements with the part="..." attribute indicate which parts are available for styling.

The UI looks broken after upgrading authentik. What should I do?¶

The upgrade may have introduced changes to the base theme, which could conflict with your custom CSS. In addition to reviewing the release notes for any changes, you may need to adjust your custom CSS to accommodate the new base styles. Avoiding direct element styling and instead relying on CSS variables and parts can help reduce the likelihood of breakage after upgrades.

I've locked myself out of authentik with a broken theme. How do I recover?¶

If you've locked yourself out of authentik due to a broken theme, you can use the recovery token to regain access. To generate a recovery token, run the following command in your terminal:

uv run ak create_recovery_key 10 akadmin

Using a recovery token will disable custom CSS, allowing you to log in, navigate to the System > Brands page, and remove or fix the broken custom CSS.