Design

Which Tool Do I Need?

Changing the Theme

The theme is a set of options that you pass to setTheme() in the dashboard configuration. All of them are optional, and you don't have to write any CSS:

The theme applies to all the pages of a dashboard, so you can't change it for only one page. Applications with two dashboards (e.g. for employees and for customers) can use two themes. The standalone login page doesn't use it.

1
2
3
4
5
6
7
8

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\ThemeColor;

// neutral, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky,
// blue, indigo, violet, purple, fuchsia, pink, rose
Theme::new()->primaryColor('indigo');

// the same colors are available as cases of the ThemeColor enum
Theme::new()->primaryColor(ThemeColor::Indigo);

1
2

Theme::new()->primaryColor('#15803d');
Theme::new()->primaryColor('#15803d', dark: '#22c55e');

1
2
3
4
5

// the presets are 'none', 'xs', 'sm', 'md', 'lg' and 'xl'
Theme::new()->radius('xl');

// you can also use any length in 'px' or 'rem'
Theme::new()->radius('0.3rem');

1
2

// the presets are 'xs', 'sm', 'md', 'lg' and 'xl'
Theme::new()->spacing('xs');

1
2
3
4
5

// these values are also available as constants of the GrayScale class
Theme::new()->grays('stone');

// use a different scale in the dark color scheme
Theme::new()->grays('stone', dark: 'neutral');

1
2
3
4
5
6
7
8

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;

// the included fonts for text are Inter, IbmPlexSans, Rubik and
// AtkinsonHyperlegibleNext (designed for low-vision readers)
Theme::new()->font(base: Font::IbmPlexSans);

// the fonts of the operating system (Segoe UI on Windows, San Francisco on macOS, etc.)
Theme::new()->font(base: Font::System, monospace: Font::System);

1

Theme::new()->font(base: 'Lexend', monospace: 'Fira Code');

1
2
3
4
5
6
7
8
9

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;
use EasyCorp\Bundle\EasyAdminBundle\Config\Option\FontFeature;

// all digits have the same width; 'ss01' is an optional style of the font
Theme::new()->font(
    base: Font::Inter,
    baseWeight: 450,
    features: [FontFeature::TabularNumbers, 'ss01'],
);

Layout, Logo and Other Options

The dashboard configuration includes other options that change the look of the backend:

• setTitle() and setFaviconPath() define the name and icon of your backend. The title can contain HTML, so you can display a logo;
• setDefaultColorScheme() defines the color scheme of users who haven't selected one ('auto' follows the operating system) and disableDarkMode() removes the dark mode. If your CSS isn't ready for dark mode, use this temporarily;
• setBadgeVariant() changes the look of badges: 'light' (default), 'solid', 'outline' or 'dot'. Call it in the configureCrud() method of your dashboard (for all the backend) or of a CRUD controller;
• renderContentMaximized() makes the content as wide as the browser window and renderSidebarMinimized() displays the sidebar as a narrow column of icons. You can also call them in the configureCrud() method of a CRUD controller.

Users can change these widths with the two buttons on the edges of the content, and their browser remembers that choice. If you call one of these methods, your configuration applies whenever a page loads, and the buttons only change the width until the next page.

Trying Designs in the UI Kit

The UI Kit is a set of pages inside your own dashboard where you can try the predefined colors and fonts and get the PHP code of your selection. It also shows all the HTML elements and Twig components with their code, using your theme and your CSS. Open _ea_ui_kit under the URL of your dashboard (e.g. /admin/_ea_ui_kit) or use the link in the EasyAdmin panel of the Symfony Profiler.

The UI Kit also has a form with the form fields of EasyAdmin. It shows them the same way as your CRUD forms, so it's useful to check your CSS changes on a single page. Use the buttons above the form to see the fields with help messages, with validation errors or disabled.

The UI Kit is only available in debug mode, so it doesn't exist in production. To enable it elsewhere (e.g. in a demo server) or disable it in debug mode, use this parameter:

1
2
3

# config/services.yaml
parameters:
    easyadmin.ui_kit.enabled: true

Changing Values with CSS Variables

Use CSS variables when the theme doesn't have an option for what you want to change. Most colors and sizes of the backend are CSS variables. Change one in a CSS file and everything that uses it changes too. First, create that file in the assets/ directory and load it in your dashboard:

1
2
3
4
5
6

use EasyCorp\Bundle\EasyAdminBundle\Config\Assets;

public function configureAssets(): Assets
{
    return Assets::new()->addCssFile('styles/admin.css');
}

The path is relative to assets/, and AssetMapper adds the hash to the URL of the file. If you use Webpack Encore, import the file in an entry and call addWebpackEncoreEntry('admin') instead.

Then, redefine the variables that you want to change:

1
2
3
4
5

/* assets/styles/admin.css */
:root, .ea-dark-scheme {
    --font-size-base: 15px;
    --body-max-width: 1600px;
}

Colors usually need a different value in each color scheme. Use the light-dark() CSS function to set both:

1
2
3

:root, .ea-dark-scheme {
    --body-bg: light-dark(#fffdf7, #1c1917);
}

This function only accepts colors. For other values, use a :root rule and a separate .ea-dark-scheme rule.

These are the variables that you'll need most often:

To find the rest, inspect an element with the developer tools of your browser, or read these two files of the vendor/easycorp/easyadmin-bundle/assets/css/easyadmin-theme/ directory:

• design-tokens.css defines the few global values that the rest of the design derives from, such as --ea-spacing;
• variables-theme.css defines the hundreds of specific values, such as --sidebar-bg.

Prefer the theme for the primary color, the radius, the spacing and the gray colors. It does things that CSS can't do: for example, primaryColor() also calculates the color of the text on top of the primary color and of the check icons.

Writing Your Own CSS

When no variable does what you need, write your own CSS. It wins over the theme, and the theme wins over the default design. You don't need !important or very specific selectors, because all the EasyAdmin styles are in CSS cascade layers. For example, this displays the logo in shades of gray:

1
2
3

.ea-sidebar-logo img {
    filter: grayscale(1);
}

Use these CSS classes and attributes to target a specific page:

The <entity_name> is the short class name (e.g. BlogPost). On index pages without results, the id is empty and the only class is ea-index.

These other classes and attributes are also available:

• The <body> also has the ea-light-scheme or ea-dark-scheme class;
• In tables, the cells of a column have the data-column="<property>" attribute and the CSS class of the field (e.g. field-money);
• On all pages, you can add your own class to a field with addCssClass();
• Actions have the action-<name> class (e.g. action-delete).

For example, this displays order totals in bold in the listing, and changes the background of a field on all pages:

1
2
3
4
5
6
7
8

.ea-index-Order td[data-column="total"] {
    font-weight: var(--font-weight-semibold);
}

/* after calling addCssClass('is-important') in the field */
.is-important {
    background: var(--secondary-bg);
}

If CSS isn't enough because you need different HTML, read Customizing Templates.

Recipes

These are ready to copy. The PHP code goes in your dashboard, unless otherwise noted. The CSS code goes in your CSS file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\ThemeColor;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

public function __construct(
    #[Autowire(env: 'APP_STAGE')] private string $stage,
) {
}

public function configureDashboard(): Dashboard
{
    $isProduction = 'production' === $this->stage;
    $testBadge = '<span class="badge badge-danger">TEST</span>';

    return Dashboard::new()
        ->setTitle($isProduction ? 'Acme' : 'Acme '.$testBadge)
        ->setTheme(Theme::new()
            ->primaryColor($isProduction ? '#c2410c' : ThemeColor::Red)
        );
}

1
2
3
4
5
6
7
8
9
10
11
12
13

use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;

public function configureDashboard(): Dashboard
{
    return Dashboard::new()
        ->setTheme(Theme::new()->spacing('xs'))
        ->renderContentMaximized();
}

public function configureCrud(): Crud
{
    return Crud::new()->setPaginatorPageSize(50);
}

1
2
3
4

/* optional: spacing() doesn't change the size of the text */
:root, .ea-dark-scheme {
    --font-size-base: 13px;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;
use EasyCorp\Bundle\EasyAdminBundle\Config\Option\ThemeColor;

// friendly: round corners, more space, warm grays
Theme::new()
    ->primaryColor(ThemeColor::Rose)
    ->radius('xl')
    ->spacing('lg')
    ->grays('stone')
    ->font(base: Font::Rubik);

// technical: square corners, less space, cool grays
Theme::new()
    ->primaryColor(ThemeColor::Blue)
    ->radius('none')
    ->spacing('sm')
    ->grays('slate')
    ->font(base: Font::IbmPlexSans);

1
2
3

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;

Theme::new()->font(base: Font::AtkinsonHyperlegibleNext)->spacing('lg');

1
2
3

:root, .ea-dark-scheme {
    --font-size-base: 15px;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

:root, .ea-dark-scheme {
    --sidebar-bg: #0f172a;
    --sidebar-border-color: #334155;
    --sidebar-logo-color: #fff;
    --sidebar-menu-color: #cbd5e1;
    --sidebar-menu-submenu-color: #94a3b8;
    --sidebar-menu-header-color: #94a3b8;
    --sidebar-menu-icon-color: #94a3b8;
    --sidebar-menu-active-item-bg: #1e293b;
    --sidebar-menu-active-item-color: #fff;
    --sidebar-menu-hover-color: #fff;
    --sidebar-item-hover-bg: #1e293b;
    /* on small screens, a header replaces the sidebar */
    --responsive-header-bg: #0f172a;
    --responsive-header-logo-color: #fff;
}

1

Dashboard::new()->setTitle('<img src="/images/logo.svg" alt="Acme" height="28">');

1
2
3
4

Dashboard::new()->setTitle(
    '<img class="logo-light" src="/images/logo.svg" alt="Acme" height="28">'
    .'<img class="logo-dark" src="/images/logo-dark.svg" alt="Acme" height="28">'
);

1
2
3
4

.ea-dark-scheme .logo-light,
.ea-light-scheme .logo-dark {
    display: none;
}

1
2
3

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;

Theme::new()->font(base: Font::System);

1
2
3
4
5
6
7
8
9

@font-face {
    font-family: 'Acme Sans';
    src: url('/fonts/acme-sans.woff2') format('woff2');
    font-weight: 400 700;
}

:root, .ea-dark-scheme {
    --font-family-sans-serif: 'Acme Sans', var(--font-family-system-sans-serif);
}

1
2
3
4

public function configureCrud(Crud $crud): Crud
{
    return $crud->renderContentMaximized();
}

1
2
3

body.ea-index-Order {
    --body-max-width: 1800px;
}

1
2
3
4

public function configureCrud(Crud $crud): Crud
{
    return $crud->overrideTemplate('crud/index', 'admin/order/index.html.twig');
}

1
2
3
4
5
6

{# templates/admin/order/index.html.twig #}
{% extends '@EasyAdmin/crud/index.html.twig' %}

{% block entity_row_attributes %}
    {% if entity.instance.isOverdue %}class="is-overdue"{% endif %}
{% endblock %}

1
2
3

tr.is-overdue:not(.selected-row) td {
    background: color-mix(in oklab, var(--red-500) 12%, transparent);
}

1
2
3

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\FontFeature;

Theme::new()->font(features: [FontFeature::TabularNumbers]);

1
2
3
4
5
6

use EasyCorp\Bundle\EasyAdminBundle\Config\Option\Font;

Theme::new()
    ->primaryColor('hsl(230, 61%, 58%)', dark: 'hsl(224, 84%, 49%)')
    ->grays('slate', dark: 'neutral')
    ->font(base: Font::System, monospace: Font::System);

Styling Custom Pages

Write regular HTML in your custom pages and it will look good without any CSS. Headings, paragraphs, lists, tables, images, code blocks and more are styled automatically:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{# templates/admin/release_notes.html.twig #}
{% extends '@EasyAdmin/page/content.html.twig' %}

{% block content_title %}Release notes{% endblock %}

{% block main %}
    <p class="lead">This paragraph is displayed bigger than the others.</p>

    <h2>New features <twig:ea:Badge color="success">3</twig:ea:Badge></h2>
    <ul>
        <li>Invoices can be downloaded as PDF files.</li>
    </ul>

    {# wide tables scroll horizontally inside this element #}
    <div class="ea-prose-scroll">
        <table>...</table>
    </div>
{% endblock %}

These styles are called prose, and the UI Kit displays all of them in its Typography page. They apply to the main block of the templates that extend @EasyAdmin/page/content.html.twig:

• If you override the body_class block, call {{ parent() }} to keep the class that enables them;
• Templates that extend @EasyAdmin/layout.html.twig don't get these styles. Make them extend @EasyAdmin/page/content.html.twig, which has the same blocks;
• Elsewhere, add the ea-prose CSS class to the element that wraps the content;
• Inside the Modal component, add the ea-prose class to an element of its body block, not to the bodyClass option.

Not everything inside those elements gets these styles:

• Add the ea-not-prose CSS class (or the data-ea-not-prose attribute) to exclude part of the content. You can't enable prose again inside that element;
• Bootstrap and EasyAdmin components (buttons, cards, tables with the table class, etc.), Bootstrap typography classes (h1, display-*, list-unstyled, etc.) and forms keep their own styles. Other CSS classes don't disable prose: <p class="text-center"> is still a styled paragraph;
• Inside an ea-prose element, components without their own text size (alerts, cards, tables, etc.) inherit its font size and line height. To use the default typography of the backend, wrap them in an ea-not-prose element. This doesn't happen in the main block of custom pages.

1
2
3
4

{% block configured_stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('css/sales_report.css') }}">
{% endblock %}

To change these styles, use these variables, either for the entire backend or only in part of a page (e.g. <div class="ea-prose release-notes">):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

:root, .ea-dark-scheme {
    --ea-prose-font-size: 16px;
    --ea-prose-line-height: 1.8;
    /* the space between paragraphs, lists, tables, etc.; all vertical gaps are
       multiples of this value */
    --ea-prose-spacing: 1.5em;
    --ea-prose-font-family: Georgia, serif;
    --ea-prose-heading-font-family: Georgia, serif;
    --ea-prose-code-font-family: 'Fira Code', monospace;
}

.ea-prose.release-notes {
    --ea-prose-line-height: 1.5;
}

The colors use the --prose-* variables of variables-theme.css (e.g. --prose-link-color, --prose-code-color). Links are blue here to make them visible in long texts, and they use the text color in the rest of the interface.

Two exceptions: --prose-color only applies to elements with the ea-prose class, and --heading-font-weight, --heading-letter-spacing and --link-font-weight also change the rest of the backend.

Using EasyAdmin Twig Components

Before writing HTML and CSS for a button or a badge, use the Twig Components of EasyAdmin. They are already installed, they look like the rest of the backend and they follow your theme:

1
2
3
4
5

<twig:ea:Button color="primary" htmlElement="a" href="{{ invoice_url }}">
    Download invoice
</twig:ea:Button>
<twig:ea:Badge color="success">Paid</twig:ea:Badge>
<twig:ea:Alert variant="warning">This invoice is overdue.</twig:ea:Alert>

Read the Twig Components reference to learn about all of them (buttons, badges, icons, modals, dropdown menus, etc.) and see them live in the UI Kit.

Customizing Templates

Change the templates only when you need different HTML. For anything else, use CSS: it's safer, because your copied templates may need changes when you upgrade EasyAdmin. For the same reason, change only the Twig blocks that you need. You can modify backend templates in two ways:

• Override EasyAdmin templates using Symfony's mechanism to override templates (this is the same for all bundles, not only EasyAdmin);
• Replace EasyAdmin templates using EasyAdmin features. This is more powerful, because you can use different templates per CRUD controller.

1
2
3
4
5
6
7
8
9
10

your-project/
├─ ...
└─ templates/
   └─ bundles/
      └─ EasyAdminBundle/
         ├─ layout.html.twig
         └─ crud/
            ├─ index.html.twig
            └─ field/
               └─ text.html.twig

1
2
3
4
5
6
7
8
9
10
11

{# templates/bundles/EasyAdminBundle/layout.html.twig #}

{# DON'T DO THIS: it will cause an infinite loop #}
{% extends '@EasyAdmin/layout.html.twig' %}

{# DO THIS: the '!' symbol tells Symfony to extend from the original template #}
{% extends '@!EasyAdmin/layout.html.twig' %}

{% block content_title %}
    {# ... #}
{% endblock %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;

#[AdminDashboard(routePath: '/admin', routeName: 'admin')]
class DashboardController extends AbstractDashboardController
{
    // ...

    public function configureCrud(): Crud
    {
        return Crud::new()
            // ...

            // the first argument is the "template name", which is the same as the
            // Twig path but without the `@EasyAdmin/` prefix
            ->overrideTemplate('label/null', 'admin/labels/my_null_label.html.twig')

            ->overrideTemplates([
                'crud/index' => 'admin/pages/index.html.twig',
                'crud/field/textarea' => 'admin/fields/dynamic_textarea.html.twig',
            ])
        ;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

namespace App\Controller\Admin;

use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractCrudController;

class ProductCrudController extends AbstractCrudController
{
    // ...

    public function configureCrud(Crud $crud): Crud
    {
        return $crud
            // ...

            ->overrideTemplate('layout', 'admin/advanced_layout.html.twig')

            ->overrideTemplates([
                'crud/field/text' => 'admin/product/field_id.html.twig',
                'label/null' => 'admin/labels/null_product.html.twig',
            ])
        ;
    }
}

1
2
3
4
5
6

public function configureCrud(Crud $crud): Crud
{
    return $crud
        ->overrideTemplate('crud/detail/fieldset_open', 'admin/detail/fieldset_open.html.twig')
    ;
}

1

IntegerField::new('stock')->setTemplatePath('admin/fields/stock.html.twig');

1
2
3
4

{# templates/admin/fields/stock.html.twig #}
<twig:ea:Badge color="{{ field.value > 0 ? 'success' : 'danger' }}">
    {{ field.formattedValue }}
</twig:ea:Badge>

1
2
3

Action::new('invoice', 'Invoice')
    // ...
    ->setTemplatePath('admin/actions/invoice.html.twig');

1
2
3
4
5

TextField::new('title')
    // ...
    ->setFormTypeOptions([
        'block_name' => 'custom_title',
    ]);

1
2
3
4
5
6
7
8

{# templates/admin/form.html.twig #}
{# note that the Twig block name starts with an uppercase letter
   ('_Product_...' instead of '_product_...') because the first part
   of the block name is the unmodified entity name #}
{% block _Product_custom_title_widget %}
    {# ... #}
    <a href="...">More information</a>
{% endblock %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

namespace App\Controller\Admin;

use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractCrudController;

class ProductCrudController extends AbstractCrudController
{
    // ...

    public function configureCrud(Crud $crud): Crud
    {
        return $crud
            // ...

            // don't forget to add EasyAdmin's form theme at the end of the list
            // (otherwise you'll lose all the styles for the rest of form fields)
            ->setFormThemes(['admin/form.html.twig', '@EasyAdmin/crud/form_theme.html.twig'])
        ;
    }
}

Changing the Backend Icons

By default, EasyAdmin uses FontAwesome icons both for the built-in interface icons and any custom icons that you add to menu items, fields, form tabs, etc. The full FontAwesome icon set (~2,000 icons) is already included in EasyAdmin, so you don't need to download any of these icons.

If you prefer to use other icons, call the useCustomIconSet() method in your dashboard:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

namespace App\Controller\Admin;

use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminDashboard;
use EasyCorp\Bundle\EasyAdminBundle\Config\Assets;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractDashboardController;

#[AdminDashboard(routePath: '/admin', routeName: 'admin')]
class DashboardController extends AbstractDashboardController
{
    public function configureAssets(): Assets
    {
        return Assets::new()
            ->useCustomIconSet()
        ;
    }

    // ...
}

Then, whenever you define a custom icon for any EasyAdmin feature, use the full icon prefix and name (lucide:map-pin, ic:baseline-calendar-month, etc.) that you would typically use in Symfony UX Icons.

If all your icons use a common prefix (e.g. tabler: when using the Tabler icons), pass it to the useCustomIconSet() method:

1

return Assets::new()->useCustomIconSet('tabler');

Now, the tabler: prefix will be added automatically to all your custom icon names. This way, you can use names like user and file instead of tabler:user and tabler:file.

Customizing Flash Messages

EasyAdmin displays the flash messages added by your application using the ea:Alert Twig component. Flash messages are usually plain strings, which are translated using the translation domain configured in the dashboard:

1

$this->addFlash('success', 'post.published');

To add a title or an icon, pass an array with a mandatory message key and optional title and icon keys:

1
2
3
4
5

$this->addFlash('success', [
    'message' => 'post.published',
    'title' => 'post.published.title',
    'icon' => 'fa-circle-check',
]);

The message and title values are translated like plain string flash messages; the icon value accepts the same values as the ea:Icon Twig component (icon names from the icon set configured in the backend).

Adding Custom Web Assets

Use the configureAssets() method in the dashboard and/or the CRUD controllers to add your own CSS and JavaScript files:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

namespace App\Controller\Admin;

use EasyCorp\Bundle\EasyAdminBundle\Config\Assets;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractCrudController;

class ProductCrudController extends AbstractCrudController
{
    // ...

    public function configureAssets(Assets $assets): Assets
    {
        return $assets
            // imports the given entrypoint defined in the importmap.php file of AssetMapper
            // it's equivalent to adding this inside the <head> element:
            // {{ importmap('admin') }}
            ->addAssetMapperEntry('admin')
            // you can also import multiple entries
            // it's equivalent to calling {{ importmap(['app', 'admin']) }}
            ->addAssetMapperEntry('app', 'admin')

            // adds the CSS and JS assets associated with the given Webpack Encore entry
            // it's equivalent to adding these inside the <head> element:
            // {{ encore_entry_link_tags('...') }} and {{ encore_entry_script_tags('...') }}
            ->addWebpackEncoreEntry('admin-app')

            // adds the CSS and JS assets associated with the given Symfony Reprise entry
            // it's equivalent to adding these inside the <head> element:
            // {{ reprise_entry_link_tags('...') }} and {{ reprise_entry_script_tags('...') }}
            ->addRepriseEntry('admin-app')

            // it's equivalent to adding this inside the <head> element:
            // <link rel="stylesheet" href="{{ asset('...') }}">
            ->addCssFile('build/admin.css')
            ->addCssFile('https://example.org/css/admin2.css')

            // it's equivalent to adding this inside the <head> element:
            // <script src="{{ asset('...') }}"></script>
            ->addJsFile('build/admin.js')
            ->addJsFile('https://example.org/js/admin2.js')

            // use these generic methods to add any code before </head> or </body>
            // the contents are included "as is" in the rendered page (without escaping them)
            ->addHtmlContentToHead('<link rel="dns-prefetch" href="https://assets.example.com">')
            ->addHtmlContentToBody('<script> ... </script>')
            ->addHtmlContentToBody('<!-- generated at '.time().' -->')
        ;
    }
}

If you need to customize the HTML attributes or other features of the <link> and <script> tags, pass an Asset object to the addCssFile(), addJsFile(), addWebpackEncoreEntry() and addRepriseEntry() methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

use EasyCorp\Bundle\EasyAdminBundle\Config\Asset;
// ...

return $assets
    ->addCssFile(Asset::new('build/admin.css')->preload()->nopush())
    ->addCssFile(Asset::new('build/admin-print.css')->htmlAttr('media', 'print'))

    ->addJsFile(Asset::new('build/admin.js')->defer())
    ->addJsFile(Asset::new('build/admin.js')->preload())
    ->addJsFile(Asset::new('build/admin.js')->htmlAttr('referrerpolicy', 'strict-origin'))

    ->addWebpackEncoreEntry(Asset::new('admin-app')->webpackEntrypointName('...'))

    // Symfony Reprise entries only support defining the Symfony Asset package
    // that they belong to; the HTML attributes of their <link> and <script>
    // tags are configured globally in the Symfony Reprise bundle configuration
    ->addRepriseEntry(Asset::new('admin-app')->reprisePackageName('...'))

    ->addCssFile(Asset::new('build/admin-detail.css')->onlyOnDetail())
    ->addJsFile(Asset::new('build/admin.js')->onlyWhenCreating())
    ->addWebpackEncoreEntry(Asset::new('admin-app')->ignoreOnForm())

    // you can also define the Symfony Asset package which the asset belongs to
    ->addCssFile(Asset::new('css/legacy.css')->package('legacy_assets'))
;

Use async() to add the async attribute to the <script> tag and htmlAttrs() to set several HTML attributes at once (instead of calling htmlAttr() repeatedly). Webpack Encore entries also accept webpackPackageName() to define the Symfony Asset package used to load them:

1
2
3
4
5
6
7
8

return $assets
    ->addJsFile(Asset::new('build/admin.js')->async())
    ->addCssFile(Asset::new('build/admin.css')->htmlAttrs([
        'media' => 'print',
        'data-turbo-track' => 'reload',
    ]))
    ->addWebpackEncoreEntry(Asset::new('admin-app')->webpackPackageName('...'))
;

Assets are added to all pages by default. Restrict them to some pages with the following methods:

• onlyOnDetail(), onlyOnIndex(), onlyOnForms(), onlyWhenCreating() and onlyWhenUpdating() add the asset only to those pages;
• ignoreOnDetail(), ignoreOnIndex(), ignoreOnForm(), ignoreWhenCreating() and ignoreWhenUpdating() add the asset to all pages except those.

Content Security Policy (CSP) Support

Content Security Policy (CSP) is a security feature that helps prevent cross-site scripting (XSS) and other code injection attacks. When your application uses strict CSP headers, all inline scripts and dynamically loaded scripts must include a cryptographic nonce to be executed by the browser.

To use CSP nonces, install and configure NelmioSecurityBundle in your application. EasyAdmin detects the csp_nonce() Twig function and adds the nonce attribute to all its script tags.

1
2
3
4
5

{% guard function csp_nonce %}
    <script src="{{ asset('js/custom.js') }}" nonce="{{ csp_nonce('script') }}"></script>
{% else %}
    <script src="{{ asset('js/custom.js') }}"></script>
{% endguard %}

Troubleshooting

The backend is displayed without any styles. The assets of the bundle weren't installed in the public/bundles/ directory of your application. Install them with this command (remove the --symlink option if your system doesn't support symbolic links):

1

$ php bin/console assets:install --symlink

My CSS file doesn't apply. Check in your browser that the file is loaded. The path of addCssFile() is relative to the assets/ directory if you use AssetMapper (e.g. styles/admin.css) and to the public/ directory otherwise. Your browser may also be using an old version of the file.

My CSS rule doesn't win. The element has a Bootstrap utility class that uses !important. See CSS Cascade Layers.

My CSS variable only works in the light color scheme. You used the :root selector. Use :root, .ea-dark-scheme.

The UI Kit returns a 404 error. It's only available in debug mode.

My Google Font doesn't load. Check its name, because EasyAdmin doesn't validate it. Otherwise, your Content Security Policy is blocking it. See the section about fonts.

My custom page doesn't have the default text styles. The template extends @EasyAdmin/layout.html.twig or it overrides body_class without calling parent(). See the section about custom pages.

Reference