@apostrophecms/ui

The @apostrophecms/ui module provides the components and mixins for creating the admin UI seen by logged-in users with editing privileges. It also provides the UI styling with some built-in theming capabilities that can be leveraged to create a custom admin experience. This module has no impact on the experience of ordinary logged-out site visitors.

Options

Property	Type	Description
widgetMargin	String	CSS margin value for widget spacing, default is '20px 0'

widgetMargin

This option sets the padding on nested areas and only impacts what a logged-in user with editing privileges will see. It has no impact on the CSS for logged-out users or users without editing privileges.

Core Components

The @apostrophecms/ui module provides the following key UI components:

Basic UI Components

• AposButton - Button component with various styles and states
• AposCheckbox - Checkbox input component
• AposSelect - Dropdown select component
• AposToggle - Toggle switch component
• AposIndicator - Icon display component
• AposSpinner / AposLoading - Loading indicators

Layout Components

• AposTable - Table for displaying data
• AposTree - Hierarchical tree display
• AposSlatList - List component for "slats" (item cards)
• AposContextMenu - Context menu for dropdown actions
• AposPager - Pagination component

Interaction Components

• AposFile - File upload component
• AposLocalePicker - Locale selection component
• AposTagList / AposTag - Tag management components

Admin UI Customization

The @apostrophecms/ui module provides the foundation for customizing the admin interface. For complete guidance on customizing the admin UI, refer to the Customizing the User Interface guide.

Common customization options include:

• Overriding standard components by placing files with the same name in project modules
• Adding custom field types to extend schema capabilities
• Creating custom manager view columns to display piece-specific data
• Defining custom context menu operations for documents

Theming

CSS Variables

ApostropheCMS uses CSS variables for consistent styling across the admin UI. These variables are defined in the modules/@apostrophecms/ui/ui/apos/scss/global/_theme.scss file.

Colors

--a-primary: #6516dd;           /* Default primary color */
--a-danger: #eb443b;            /* Error/danger color */
--a-success: #00bf9a;           /* Success color */
--a-warning: #ffce00;           /* Warning color */
--a-text-primary: #000;         /* Primary text color */
--a-text-inverted: #fff;        /* Inverted text color */
--a-background-primary: #fff;   /* Primary background color */

Typography

--a-family-default: -apple-system, system-ui, "BlinkMacSystemFont", "Segoe UI",
  "Roboto", "Helvetica", "Arial", sans-serif;
--a-type-base: 12px;
--a-type-label: 13px;
--a-type-large: 14px;
--a-type-heading: 22px;

Layout

--a-border-radius: 5px;
--a-border-radius-large: 10px;
--a-box-shadow: 0 3px 13px 4px rgb(0 0 0 / 8%);

Dark Mode Theme

ApostropheCMS has a built-in dark mode theme that can be activated by adding the class apos-theme-dark to either the body element or the admin-bar wrapper, as detailed below.

To activate dark mode, set the bodyClass block on the outer layout from your project layout:

<Extend templateName={outerLayout} bodyClass="apos-theme-dark" />

views/layout.jsx

TIP

To add dark mode while keeping body classes that page templates pass in, compose the string rather than replacing it. The layout receives whatever the page supplied as its own bodyClass prop:

<Extend
  templateName={outerLayout}
  bodyClass={`${bodyClass || ''} apos-theme-dark`}
/>

This is the general pattern for adding to an inherited block — see Coming from blocks and super().

In a Nunjucks layout the same block is used directly, and super() preserves any existing classes:

{% block bodyClass %}{{ super() }} apos-theme-dark{% endblock %}

You can implement a front-end UI toggle between the default light theme and the dark theme by adding and removing the apos-theme-dark class.

Color Themes

ApostropheCMS supports several pre-defined color themes that can be applied to the admin UI. These themes change the primary color used throughout the interface.

Available themes: Available themes:

• apos-theme--primary-default (Purple: #6516dd)
• apos-theme--primary-blue (Blue: #0062ff)
• apos-theme--primary-orange (Orange: #e65100)
• apos-theme--primary-aqua (Aqua: #1eacc7)
• apos-theme--primary-sun (Yellow: #f7a704)
• apos-theme--primary-green (Green: #00b075)
• apos-theme--primary-pink (Pink: #fd9ec0)

Unlike the dark theme, these classes need to be added to the admin-bar wrapper.

Server-Side Theme Configuration

ApostropheCMS has some built-in theme support in the @apostrophecms/ui module. To change the primary theme, you simply need to add a schema field named aposThemePrimary that passes a theme color as value to either:

1. The global document (applies to all users)
2. The user document (applies to a specific user, overrides global setting)

Depending on your preference, you can add the following to either the modules/@apostrophecms/global/index.js or the modules/@apostrophecms/user/index.js schema fields:

export default () => ({
  fields: {
    add: {
      aposThemePrimary: {
        type: 'select',
        label: 'Admin UI Theme',
        choices: [
          { label: 'Default (Purple)', value: 'default' },
          { label: 'Blue', value: 'blue' },
          { label: 'Orange', value: 'orange' },
          { label: 'Aqua', value: 'aqua' },
          { label: 'Yellow', value: 'sun' },
          { label: 'Green', value: 'green' },
          { label: 'Pink', value: 'pink' }
          // Add your custom themes here shown below
          { label: 'Custom', value: 'custom' }
        ],
        def: 'default'
      }
    },
    group: {
      appearance: {
        label: 'Appearance',
        fields: ['aposThemePrimary']
      }
    }
  }
});

With these schema additions, the existing getBrowserData method in the UI module will automatically detect and apply the theme settings to the admin-bar wrapper HTML markup.

Creating Custom Themes

You can create your own custom theme by:

1. Creating a new SCSS file in your project (e.g., modules/asset/ui/src/scss/custom-theme.scss)
2. Adding the modern Sass module imports along with Apostrophe's mixins:

// Required for using the core ApostropheCMS Sass mixins
@use 'sass:math';
@use 'sass:color';

// Import Apostrophe's mixins
@import 'apostrophe/modules/@apostrophecms/ui/ui/apos/scss/mixins/_theme_mixins';

// Custom theme definition
// change "custom" to give your theme a different name
// and pass it in the schema above as value
.apos-theme--primary-custom {
  @include apos-primary-mixin(#ff5722); // Your custom primary color

  // You can also override other CSS variables within this selector
  --a-warning: #ffa000;
  --a-success: #00c853;
  --a-border-radius: 8px;
}

// Optional: Create a dark variant of your custom theme
// Note that the `.apos-theme-dark` can be added to the
// body or to the same wrapper div as the `.apos-theme--primary-XXX`
.apos-theme-dark .apos-theme--primary-custom {
  // Override specific variables for dark + custom combo
  --a-primary-light-40: #ff8a65;
  --a-base-9: #212932;
  --a-base-10: #171d24;
}

Related Documentation

• Customizing the User Interface
• Custom Schema Field Types
• Editing Custom Widgets in Context