Essentials Appearance
Essentials Appearance changes how Pelican Panel looks: a ready-made style or your own, accent and surface colours, layout, corners, spacing, lettering, icons, backgrounds and custom CSS. It also dresses the sign-in screen, adds links of your own to the sidebar, styles the server cards and the console, and can let each person pick a style for themselves. It is for administrators who want the panel to look like their own community rather than stock Pelican.
The page editor (arranging blocks on a page, elements of your own, custom pages) is not part of this plugin since 1.3.0; that is Essentials Arranger.
At a glance
| Plugin ID | essentials-appearance |
| Current version | 1.3.3 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The frontend build (its stylesheet and script are compiled into the panel's build, so Node.js and Yarn on the panel server). No scheduler, no outside accounts |
| Works with (optional) | Essentials Core (the Parts window, health notes, the settings search box); Essentials Arranger (the page editor, which uses this plugin's icons) |
| Adds | Admin area, sidebar group Essentials Appearance: Look, Pages, Advanced, Navigation links, Login screen. Client area: Appearance in the user menu, when you offer styles to choose from. A Create an account form on the sign-in screen, only when you open it |
| Permissions | Admin -> Roles, section Essentials Appearance: View, Update, and a pair per page: Look / View Look, Pages / View Pages, Advanced / View Advanced, Links / View Links, Login / View Login |
What the permissions mean:
- View and Update: every page of this plugin, to look at and to change.
- Each pair gives one page on its own: the View half opens it, the other half lets the role save it. Links is the Navigation links page and Login the Login screen page.
- Export settings, Import settings and the Parts window ask for Update.
- Until Essentials Arranger 1.1.0 or later is installed, the section also still holds the page editor's permissions (Arrange, and Arranger, Blocks and Custom Pages with their view halves), so roles keep them until Arranger takes them over.
Before you install
- The look changes the moment it is installed. On a panel that never had Essentials, the style is Ember (warm black, orange accent), the panel opens in dark mode and Force dark mode is on, which hides the light/dark switcher for everyone. To get Pelican's own look back, set Style to None on the Look page. A panel that came from the all-in-one keeps the look it had: its
LEGEND_THEME_*settings in.envare read until you save the pages here. - The panel does not run the legacy all-in-one plugin "Essentials" (plugin id
essentials). Never run it on the same panel as anyessentials-*module: installing a module switches the all-in-one off, installing the all-in-one can switch modules off, and uninstalling the all-in-one deletes database tables the modules share. Pick one. If an older all-in-one is still enabled, this plugin refuses to start and says so. - Essentials Core is installed, or you accept that the parts of this plugin cannot be switched on and off. The Parts window lives on Core's Essentials page.
- Pelican Panel 1.0 is installed. Pelican 1.0.0-rc.2 needs PHP 8.4 or 8.5.
- Node.js and Yarn are installed on the panel server, and the build runs as the panel's web user. Without the build the plugin's stylesheet is missing, and most of the look does not apply.
- For installs started from the admin area, the queue worker runs. This is Pelican's background worker, usually the systemd service
pelican-queue. Check it withsystemctl status pelican-queue.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Appearance and a version, and download the zip. x.y.z is stable, x.y.z-beta is a test release and x.y.z-dev is a development build. Use stable on a live panel.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. Press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key (made under Admin -> API keys, with read and write on Plugins; it starts with
papp_), then use Install on the plugin's page on the website. -
With the Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). The examples here assume Pelican lives in
/var/www/pelicanand the web server user iswww-data(Debian and Ubuntu); on another setup, adapt the path and the user (for examplenginxon some systems). Unzip so the folder is exactly/var/www/pelican/plugins/essentials-appearance, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-appearance cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-appearance sudo -u www-data php artisan p:plugin:listThe list must say enabled. Unzipping over an existing plugin folder resets it to "not installed", so run the install command again after every unzip.
What the install does:
- It creates no database tables and runs no migrations. Settings live in files under
storage/app/private/essentials/appearance/. - It clears Pelican's route and view caches and asks the queue worker to restart.
- On a panel that ran the all-in-one, it copies the permissions roles held there to its own section, once.
After every install:
- If the panel still looks unstyled, run
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core, Panel health on the Essentials page reports missing built assets. - If a new page answers 404 or an old version still shows, reload PHP-FPM (
sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue). - Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root.
First-time setup
- Open Admin, sidebar group Essentials Appearance, page Look.
- Under Appearance, pick a Style. It fills in everything below it, which you can then change. None turns the theme off and leaves the panel exactly as Pelican ships it. Then set what you want:
- Accent colour: buttons, links, the active menu item and focus rings. Under it the page shows a readability figure; under 3 an accent is hard to read.
- Panel mode (Dark, Light or System) and Force dark mode, which hides the switcher and keeps everyone on dark.
- Layout (sidebar, icon rail, top navigation and more), Sidebar style, Topbar style, Card style, Surface colour, Corners, Density, Panel lettering, Frosted topbar and Accent glow.
- Styles people may choose for themselves: tick the styles people may pick on their own Appearance page in the client area. Nothing ticked means everybody sees the panel's look.
- Open the folded sections as needed:
- Brand: Logo override and Logo height.
- Background: Aurora (the default), a single colour, a gradient or an image (upload up to 8 MB, or an https address).
- Icons: line weight, size, Icon pack, uploading a pack, and Replace icons for single menu items.
- Timed looks: a different style between two times of day, in the panel's own time zone. Nothing happens until you add a window.
- Sidebar footer: a line of text, the Pelican version and one link at the bottom of the sidebar. Off until you fill it in.
- Use the preview box beside the form, or See the whole panel to open the admin dashboard drawn with the unsaved settings (held for fifteen minutes, nothing written; Back to the settings in the bar at the top returns you to the page). Press Save.
- Open Pages for the server list (Game artwork, Condition marker, Card height, Cards across a wide screen), the Console page, the Resource meters on server cards (colours and the amber and red thresholds) and the Terminal (renderer, Colour scheme, cursor, Scrollback). Press Save.
- Open Navigation links and use Add a link for rows of your own in the sidebar: Name, Icon, Address (https:// or a path inside the panel such as
/account), Shown in, Group, Open in a new tab, and optionally Use the site's own icon. Up to 12 links. Press Save. - Open Login screen for the sign-in page: a background picture, the card's blur, width, position and solidity, a Line above the form and a Notice under the card. Leave Let people create their own account off unless you mean it (see below). Press Save.
- Optional: Advanced holds Custom CSS (up to 100 KB, loaded last so it wins), a CSS reference of the classes and variables you can use, and Per area overrides for the terminal, console, files page, edit page and other server pages.
- On the Look page, use Export settings to keep a copy of everything panel-wide as one file.
- With Essentials Core installed, press Parts on this plugin's row on the Essentials page to switch parts off that you do not want: the settings pages, Navigation links, Login screen, Resource meters, Sidebar footer, Live preview, Timed looks and Per-person styles.
- Give your admin roles the permissions under Admin -> Roles, section Essentials Appearance. Root Admins have everything already.
Things to watch out for
- Signups open the panel to strangers. With Let people create their own account on, anybody who reaches the panel can make an account. New accounts get no servers and no permissions, so check what users without a role can do before you turn it on. It is off until you turn it on, and no update turns it on for you. Separately, any Pelican OAuth provider with "create missing users" switched on (Pelican's own setting under Settings, OAuth) creates accounts on first sign-in whatever this switch says; the Login screen page lists those providers.
- None switches off more than colours. With Style set to None, the accent, panel mode, logo override, layout, custom CSS and your navigation links are not applied either. Signups and the settings pages stay.
- Custom CSS can break after a Pelican update. It is written against the class names Pelican and Filament use (the CSS reference lists them). A Pelican update can change that markup, so check your own CSS after updating Pelican. The plugin itself replaces no Pelican template, so a Pelican update cannot break signing in, but its own styling is worth a look after one as well.
- The look needs the frontend build. After a Pelican update, a plugin update or a failed build, a panel that suddenly looks like stock Pelican is missing this plugin's stylesheet in the build. Run
yarn buildas the web user. - Forced dark mode is on by default. If people ask where the light/dark switcher went, that is Force dark mode.
- Timed looks use the panel's clock, not each reader's. They do nothing while the style is None, and a style somebody picked for themselves wins over them.
- Navigation link addresses must be https:// or a path inside the panel, without spaces, quotes, angle brackets or backslashes; anything else is ignored. Use the site's own icon fetches the icon once, when you save.
- Replace icons takes an uploaded PNG or ICO, or an https address. SVG files cannot be uploaded there (from 1.3.3 on), because uploads are served from the panel's own address; use an icon from a pack for an SVG icon.
- Icon packs: a pack is a .zip of SVG files; uploading replaces the pack that is there. Icons over 256 KB and anything past 4,000 icons are left out. A large upload can also be refused by
upload_max_filesizeandpost_max_sizein the panel host'sphp.ini, which no setting here can raise. - Export files carry uploaded pictures and icon sets by name only, not the files themselves. Importing on another panel leaves out pictures that are not there and names them.
- Switching a part off hides its page. Its settings are kept. Switch it back on in the Parts window on Core's Essentials page; without Core there is no window to do that in.
- Saving a role while this plugin is switched off removes its permissions from that role. Pelican only keeps the checkboxes it draws. Give them again after switching the plugin back on.
- A blank console with everything else looking right is usually the browser dropping GPU contexts. Set Drawn by under Terminal on the Pages page to the browser.
Things to keep an eye on
- With Essentials Core: the notes under this plugin's row on the Essentials page. They say when Per-person styles is on but no style is offered, when Timed looks is on but no window is set, and when the uploaded icon set is chosen but empty.
- Built assets under Panel health on Core's page, after every update.
- Your custom CSS and the look in general after each Pelican update.
- The readability figure under Accent colour when you change colours.
- Uploaded pictures and icon packs take space under
storage/app/public/themeandstorage/app/private/essentials/appearance/icons. - Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). - Your own backups: the settings live in
storage/app/private/essentials/appearance/settings.json, next to the custom CSS, styles and links. Includestorage/app/private/essentialsandstorage/app/public/themein the panel's backups, or keep a recent Export settings file. Thestoragefolder must stay writable by the web user.
Updating
- Download the new version and import it the same way. Pelican shows Update on the plugin when an update is known. Or let the Essentials Auto Updater do it. The plugin switches itself back on after an update through the admin area, and its settings are kept.
- Export your settings first, so you have a copy to import if something looks wrong.
- Coming from 1.1.x or 1.2.x. Those versions carried the page editor; from 1.3.0 it is Essentials Arranger's again. Updating switches Essentials Arranger back on, once, if an earlier release of this plugin switched it off. Nothing is deleted: elements, templates and custom pages stay under
storage/app/private/essentials/appearance/and pictures understorage/app/public/theme/blocks. Arranger copies the elements, templates and custom pages the first time it draws the editor; the pictures stay where they are and Arranger keeps using them there. The editor's permissions stay in this plugin's section until Arranger 1.1.0 or later takes them over.
Removing it
Uninstall the plugin under Admin -> Plugins. It has no database tables, so nothing is dropped. The panel goes back to Pelican's own look, the navigation links and the sign-up form disappear, and per-person styles stop applying.
These files stay behind:
storage/app/private/essentials/appearance/: the settings (settings.json), custom CSS, your own styles, navigation links, timed looks, uploaded icon packs, each person's chosen style (themes/) and a few markers. Page editor data from 1.1.x and 1.2.x is in here too.storage/app/public/theme/: uploaded backgrounds, sign-in pictures and icon pictures. Page editor pictures are intheme/blocks.
If you use Essentials Arranger, keep storage/app/public/theme/blocks: the pictures in Arranger's elements live there. If Arranger has not opened its editor since you updated, it also still needs storage/app/private/essentials/appearance: leave that folder too. Otherwise, remove them by hand:
sudo rm -r /var/www/pelican/storage/app/private/essentials/appearance
sudo rm -r /var/www/pelican/storage/app/public/theme
LEGEND_THEME_* lines in .env from the all-in-one are not touched.
Troubleshooting
| Problem | What to do |
|---|---|
| The panel looks like stock Pelican after installing or updating | Check that Style on the Look page is not None. If it is not, the build lacks the stylesheet: cd /var/www/pelican && sudo -u www-data yarn build, as the web user. |
| The plugin shows an error asking to update or disable legacy Essentials | The legacy all-in-one is enabled. Pick one: switch the all-in-one off, or remove this plugin. |
| "Essentials Appearance is missing resources/... Reinstall its complete plugin archive." | The plugin folder is incomplete. Import the zip again, or unzip it again and run the install command. |
| The light/dark switcher is gone | Force dark mode is on (the default). Turn it off on the Look page. |
| Appearance is missing from the user menu | Per-person styles must be on under Parts, and at least one style ticked under Styles people may choose for themselves. |
| A navigation link does not show | Check the link's On switch, its Shown in setting and that the address starts with https:// or /. With Style set to None, links are not added. |
| A settings page is missing from the sidebar | Its part is switched off under Parts, or the role lacks that page's view permission. |
| Custom CSS does nothing | Read the messages under the field: an unclosed comment, rule or brace stops the rest from applying. With Style set to None, custom CSS is not loaded. |
| The console is blank | Set Drawn by under Terminal on the Pages page to the browser. |
| An icon pack installed only partly | The message says how many icons were skipped and why. Export oversized SVGs at icon size and upload again. |
| An uploaded background or icon does not appear | Check the upload limit (8 MB for pictures) and that an address starts with https:// and is reachable from outside. |
| "The panel could not write to its storage directory" or "Could not save the settings" when saving | Make storage belong to the web user: sudo chown -R www-data:www-data /var/www/pelican/storage. |
| Unknown people are creating accounts | Turn off Let people create their own account on Login screen, and "create missing users" for each OAuth provider under Pelican's Settings, OAuth. If the Login screen page is gone, switch its part back on under Parts first: signups stay open while the page is hidden. |
| The Look page answers 500 ("array_map(): Argument #2 ($array) must be of type array, string given" in the log) after choosing the Essentials icon pack or saving an icon override | A fault in 1.3.1 and older. Update to 1.3.2 or later; the page opens again without resetting anything. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.