# How to Customize the Argo CD UI: CSS Themes, Banners, and Branding Options

> Customize your Argo CD UI with CSS themes, banners, and branding. Learn how to inject stylesheets and modify UI elements via the argocd-cm ConfigMap for a personalized experience.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-14

---

**You customize the Argo CD UI by editing the `argocd-cm` ConfigMap to inject custom stylesheets, display global announcement banners, or modify SSO login button text, with changes automatically loaded by the UI server at runtime.**

The argoproj/argo-cd repository provides a lightweight but powerful mechanism to tailor the web interface without rebuilding the application from source. By modifying specific keys in the **argocd-cm** ConfigMap, platform operators can override default styles, add informational banners, and relabel authentication buttons. These settings are defined in the `ArgoCDSettings` struct within [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go) and injected into the React frontend by the server logic in [`ui/embed.go`](https://github.com/argoproj/argo-cd/blob/main/ui/embed.go).

## Customization Options Overview

Argo CD exposes four primary UI customization vectors through ConfigMap data keys. Each option targets a specific visual element and requires no downtime to deploy.

### Custom Stylesheets (ui.cssurl)

The `ui.cssurl` key accepts either an external HTTPS URL or a local filesystem path pointing to a CSS file. The UI server injects this stylesheet into the HTML `<head>` after the default Argo CD styles, allowing your rules to override existing classes.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.cssurl: "https://example.com/my-argo-cd.css"

```

When configured, the UI fetches the stylesheet on page load and applies it globally. According to the source in [`ui/embed.go`](https://github.com/argoproj/argo-cd/blob/main/ui/embed.go), the server reads the `UiCssURL` field from settings and embeds it as a `<link>` tag in the served HTML.

### Global Announcement Banners

You can display persistent banners across all Argo CD pages using five related ConfigMap keys. These banners appear as thin bars at the top or bottom of the interface.

- **ui.bannerContent**: The text or HTML emoji to display
- **ui.bannerURL**: Optional hyperlink when users click the banner
- **ui.bannerPosition**: Either `"top"` or `"bottom"` (defaults to top)
- **ui.bannerPermanent**: When set to `"true"`, hides the close button

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.bannerContent: "🚧 Maintenance window – expect brief downtimes 🚧"
  ui.bannerURL: "https://status.example.com"
  ui.bannerPosition: "top"
  ui.bannerPermanent: "true"

```

The `ArgoCDSettings` struct in [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go) defines these fields as `UiBannerContent`, `UiBannerURL`, `UiBannerPosition`, and `UiBannerPermanent`, mapping directly to the ConfigMap keys.

### SSO Login Button Text

When using Dex or OIDC authentication, the default "Login via SSO" button label can be customized using the `ui.loginButtonText` key.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.loginButtonText: "Log in with MyCompany"

```

This value populates the `UiLoginButtonText` field in the settings struct and renders in the login component managed by the React frontend.

## Implementation Details

Understanding the source code architecture helps troubleshoot customization issues and predict reload behavior.

### Settings Retrieval (util/settings/settings.go)

The core configuration logic resides in [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go), where the `ArgoCDSettings` struct declares the UI customization fields:

- `UiCssURL string`
- `UiBannerContent string`
- `UiBannerURL string`
- `UiBannerPermanent bool`
- `UiBannerPosition string`
- `UiLoginButtonText string`

A dedicated function populates these fields by reading the `argocd-cm` ConfigMap data keys and converting them to the appropriate Go types.

### Static Asset Serving (ui/embed.go)

The [`ui/embed.go`](https://github.com/argoproj/argo-cd/blob/main/ui/embed.go) file implements the HTTP handler that serves the React application. During request processing, it checks the `UiCssURL` setting and injects a `<link rel="stylesheet">` tag into the generated HTML. Similarly, banner settings are serialized into JavaScript variables accessible by the frontend components.

### Frontend Components

Two React components consume these settings:

1. **[`ui/src/app/shared/components/layout/layout.tsx`](https://github.com/argoproj/argo-cd/blob/main/ui/src/app/shared/components/layout/layout.tsx)**: Manages the layout wrapper that renders banner elements based on the injected configuration
2. **[`ui/src/app/settings/components/appearance-list/appearance-list.tsx`](https://github.com/argoproj/argo-cd/blob/main/ui/src/app/settings/components/appearance-list/appearance-list.tsx)**: Provides a read-only view of current appearance settings in the UI settings page

## Step-by-Step Configuration Examples

### Mounting Local CSS Files

For air-gapped environments or complex stylesheets, mount a CSS file directly into the `argocd-server` pod rather than using external URLs.

First, create a ConfigMap containing your styles:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argo-custom-css
  namespace: argargocd
data:
  my-styles.css: |
    .cd-header { background: #004080; }
    .application-list .application { border-radius: 4px; }

```

Patch the Argo CD server deployment to mount this ConfigMap as a volume:

```yaml
volumes:
  - name: custom-css
    configMap:
      name: argo-custom-css
volumeMounts:
  - name: custom-css
    mountPath: /custom

```

Then reference the local path in `argocd-cm`:

```yaml
data:
  ui.cssurl: "/custom/my-styles.css"

```

The UI server resolves this path relative to the container filesystem, serving the file directly without external network calls.

### Complete Branding Example

Combine multiple customization options for a cohesive corporate branding experience:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  ui.cssurl: "https://assets.company.com/argo-theme.css"
  ui.bannerContent: "Production Environment - Authorized Access Only"
  ui.bannerPosition: "top"
  ui.bannerPermanent: "true"
  ui.loginButtonText: "Corporate SSO Login"

```

## Applying and Reloading Changes

The Argo CD UI watches the `argocd-cm` ConfigMap for changes. When you update the ConfigMap via `kubectl apply`, the UI automatically picks up new banner text and stylesheet URLs within seconds without requiring a pod restart.

However, if you mount CSS files as volumes using the ConfigMap method, you must restart the `argocd-server` pod to remount the updated filesystem contents:

```bash
kubectl rollout restart deployment argocd-server -n argocd

```

For external CSS URLs, the browser caches the stylesheet according to standard HTTP caching headers. Force a hard refresh (Ctrl+F5 or Cmd+Shift+R) to see updates immediately.

## Summary

- **Modify `argocd-cm`**: All UI customizations live in the Argo CD ConfigMap, not in source code or environment variables
- **Custom CSS**: Use `ui.cssurl` to load external stylesheets or local mounted files via [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go) configuration
- **Banners**: Configure `ui.bannerContent`, `ui.bannerURL`, `ui.bannerPosition`, and `ui.bannerPermanent` for global announcements
- **SSO Branding**: Override the login button label with `ui.loginButtonText` to match corporate identity
- **Hot Reloading**: ConfigMap changes apply automatically, but volume-mounted files require pod restarts

## Frequently Asked Questions

### Where is the Argo CD UI customization configuration stored?

All customization settings reside in the `argocd-cm` ConfigMap within the Argo CD namespace. The `argocd-server` pod reads this ConfigMap at startup and watches it for changes, parsing keys like `ui.cssurl` and `ui.bannerContent` into the `ArgoCDSettings` struct defined in [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go).

### Can I customize Argo CD UI without using an external URL for CSS?

Yes. You can mount a CSS file into the `argocd-server` pod using a Kubernetes ConfigMap or Secret, then reference the local filesystem path in the `ui.cssurl` key (for example, [`/custom/my-styles.css`](https://github.com/argoproj/argo-cd/blob/main//custom/my-styles.css)). This approach works in air-gapped environments and avoids external dependencies.

### Do I need to restart Argo CD after changing the UI banner?

No. The Argo CD UI automatically detects changes to the `argocd-cm` ConfigMap and updates banners and stylesheet references without requiring a pod restart. However, if you modify a mounted CSS file volume, you must restart the `argocd-server` Deployment to remount the updated file into the container filesystem.

### What CSS classes can I target when customizing Argo CD?

You can target any class visible in the React components, particularly those in [`ui/src/app/shared/components/layout/layout.tsx`](https://github.com/argoproj/argo-cd/blob/main/ui/src/app/shared/components/layout/layout.tsx). Common overrides include `.cd-header` for the top navigation bar, `.application-list` for the applications grid, and `.page__content` for main content areas. Use browser developer tools to inspect the specific classes rendered by the Argo CD version you are running.