Add-ons: Complete Themes


Porting a theme over to Pale Moon or updating your theme for the next version?

If you're looking for Complete Themes that are compatible with Pale Moon

How to: Create a Complete Theme

Note: this guide might be outdated and in need of updating for current versions of the browser.

This guide was originally written by Lootyhoof, the forum topic can be found here.

Please note: In order to create such themes, extensive use of CSS is required. If you currently are not confident with CSS, please take time to review tutorials such as W3Schools CSS Tutorial, as well as reviewing Mozilla-specific CSS extensions, which are used extensively in themes. It would also be worth looking at the XUL Reference, to be fully aware of how particular elements are named.

Setting up the environment

THIS SECTION IS IN NEED OF A REWRITE -- it doesn't apply to the current versions of Pale Moon and you best bet would be to use an existing complete theme as a starting point.

The easiest way to set up the environment for themes (i.e. folder structure, base files) is to extract them from the default theme used in the browser. The files can be located as follows; extract using 7-Zip (or similar):

  • Windows:
    • C:\Program Files\Pale Moon\omni.ja - extract /chrome/toolkit/skin/classic/global/ and /chrome/toolkit/skin/classic/mozapps/
    • C:\Program Files\Pale Moon\browser\omni.ja - extract /chrome/browser/skin/classic/browser
  • Linux/Unix:
    • Depending where you installed Pale Moon, this will be browser/omni.ja and omni.ja within the installation folder.
  • MacOS:
    • Finder - Applications - Pale Moon - CTRL+Click - Show package contents - Content - Resources
    • In this folder you will want browser/omni.ja and omni.ja.

Note that on Windows, if the Pale Moon folder is not located in Program Files, it might be in Program Files (x86), or in the location where you installed Pale Moon. Also note that the Aero theme is used due to additional stylings for Aero; it will still work on non-Aero systems (e.g. WinXP, Linux).

Once these three folders have been extracted somewhere, they should be placed in a new folder called chrome. As such, your current folder structure should be:

  • chrome
    • browser
      • [contents of /browser]
    • global
      • [contents of /global]
    • mozapps
      • [contents of /mozapps]
Aside from a few additional files to be added into the folder containing the chrome folder, this is the entire default theme, and will work perfectly. For these additional files, there will be a total of 3: install.rdf, chrome.manifest and icon.png. Let's start by making install.rdf. Copy the following into a text editor and save as "install.rdf", ensuring that it is not saved instead as "install.rdf.txt":

<?xml version="1.0"?>

<!-- This Source Code is subject to the terms of the Mozilla Public License
   - version 2.0 (the "License"). You can obtain a copy of the License at
   - -->

<RDF xmlns=""

  <Description about="urn:mozilla:install-manifest">
    <em:name>Name Here</em:name>
    <em:description>Description Here</em:description>
    <em:creator>Your Name</em:creator>


Please note that this will NOT work as-is, and is provided as template only. Please see the Install Manifests page for more information.

For chrome.manifest, copy the following into a text editor and save, replacing "namehere" with the same name you used in install.rdf:

skin browser namehere chrome/browser/
skin mozapps namehere chrome/mozapps/
skin global namehere chrome/global/

For icon.png, this is a 64x64 icon that will be used to display your theme on both about:addons and on the Pale Moon Add-ons Site.

Understanding the CSS files

As these CSS files will, in total, style the entire browser, each serves a particular purpose, and as such not all of them need changing, depending on what you want to do with your theme. In fact, for most themes, hardly any is changed, compared to the amount of files that are available, as they serve their job well and most theme authors are reasonably content with how they are styled. As such, here's a run-down of each CSS file in the default theme:

Application styles (browser)

/browser Description /browser Description
aboutCertError.css styling for SSL error pages sanitizeDialog.css styling for the "clear recent history" window
aboutPrivateBrowsing.css styling for the private browsing information page searchbar.css search bar styling (buttons etc; main styling is in browser.css)
aboutSessionRestore.css styling for the session restore page setDesktopBackground.css styling for the "set desktop background" window
aboutSyncTabs.css styling for the synced tabs page syncCommon.css common styling for sync dialogs
autocomplete.css styling for the address bar history drop-down syncProgress.css styling for sync progress page
browser.css main browser styling (e.g. tab styles, toolbar icons, etc). syncQuota.css styling for sync quota window
engineManager.css styling for the search engine manager window syncSetup.css styling for sync setup dialog
pageInfo.css styling for the page info window
/browser/downloads Description /browser/feeds Description
allDownloadsViewOverlay.css styling for the all downloads view in the places window subscribe.css styling for the feed subscribe page
contentAreaDownloadsView.css styling for about:downloads subscribe-ui.css styling for the controls on the feed subscribe page
downloads.css general downloads styling, including both icons and popups for the downloads manager (only applicable if NOT using the "classic" download window)
/browser/places Description /browser/newtab Description
editBookmarkOverlay.css styling for the "edit bookmark" dialog used when clicking on the bookmark button on an already-bookmarked site newTab.css styling for the new tab page
organizer.css styling for the toolbars/menus in the places window (history/bookmarks manager) /browser/permissions Description
places.css styling for the content of the places window aboutPermissions.css styling for permissions manager page (about:permissions).
/browser/preferences Description /browser/statusbar Description
applications.css styling for the applications tab in Preferences window dynamic.css styling for the progress bar in the status bar
preferences.css styling for the Preferences window overlay.css styling for controls placed in the status bar (includes the Downloads Status button, progress meter and status widgets, and Status Bar preferences button)
prefs.css styling for the status bar's preferences window

Toolkit styles (global and mozapps)

/global Description /global Description
about.css common styling for "About" pages (e.g. about:about) menu.css common styling for menus
aboutCache.css styling for about:cache menulist.css common styling for menulists
aboutCacheEntry.css styling for entries in about:cache netError.css common styling for various error pages
aboutMemory.css styling for about:memory notification.css styling for notifications. (NOT including desktop notifications - see alert.css in /global/alert)
aboutReader.css styling for reader view numberbox.css common styling for numberboxes
aboutSupport.css styling for about:support passwordmgr.css styling for the password manager
appPicker.css styling used for the dialog in selecting a default application popup.css styling for the notification popup
arrow.css common styling for arrows preferences.css common styling for preferences windows
autocomplete.css common styling for autocomplete (e.g. in urlbar) printPageSetup.css styling for the printer page setup dialog
buttton.css common styling for buttons printPreview.css styling for the print preview dialog
checkbox.css common styling for checkboxes progressmeter.css styling for progress meters
colorpicker.css common styling for color pickers radio.css styling for radio buttons
commonDialog.css common dialog styling resizer.css styling for the window resizer (usually shown in windows that can be resized)
config.css styling for about:config richlistbox.css common styling for richlistboxes
customizeToolbar.css styling for the "customize toolbar" dialog scale.css common styling for sliders
datetimepicker.css common styling for date/time pickers scrollbars.css scrollbar styling
dialog.css styling for dialogs scrollbox.css common styling for scrollboxes
dropmarker.css common styling for dropmarkers spinbuttons.css common styling for spinbuttons
expander.css common styling for expanders splitter.css common styling for splitters
filefield.css common styling for file select fields tabbox.css common styling for tabboxes (groups of tabs, e.g. as seen in Preferences - Advanced)
filepicker.css common styling for file pickers tabprompts.css styling for in-page alert boxes
findbar.css find bar styling textbox.css common styling for textboxes
global.css common styling for various UI elements (e.g. windows, dialogs, status bars, separators) toolbar.css common toolbar styling
groupbox.css common styling for groupboxes toolbarbutton.css common toolbar button styling
inContentUI.css common styling for "in-content pages (e.g. about:addons) tree.css common tree styling
linkTree.css common styling for link trees wizard.css common wizard window styling (e.g. Migrator window)
listbox.css common styling for listboxes
/global/alert Description /global/console Description
alert.css styling for desktop notifications console.css styling for the toolkit error console
/global/dirListing Description /global/media Description
dirListing.css styling for directory listings TopLevelImageDocument.css styling for pages when viewing individual images
global/in-content Description TopLevelVideoDocument.css styling for pages when viewing individual videos
common.css common styling for in-content pages (used only in PM v28+) videocontrols.css styling for HTML5 native video player
info-pages.css common styling for info pages (e.g. network error) (used only in PM v28+)
/mozapps Description /mozapps/xpinstall Description
aboutNetworking.css styling for about:networking page xpinstallconfirm.css styling for the add-on install popup window
aboutProfiles.css styling for about:profiles page
aboutServiceWorkers.css styling for about:serviceworkers page
/mozapps/downloads Description /mozapps/extensions Description
downloads.css styling for the "classic" downloads window about.css styling for the about window when right-clicking an add-on
unknownContentType.css styling for the unknown content handler blocklist.css styling for the blocklist
/mozapps/formautofill Description eula.css styling for providing an add-on's EULA
requestAutocomplete.css Unknown extensions.css main styling for the add-ons manager page (about:addons)
/mozapps/handling Description newaddon.css styling for the add-on confirmation page for suspiciously-enabled add-ons
handler.css Unknown selectAddons.css styling for add-on selection
update.css styling for the add-on updater
/mozapps/plugins Description /mozapps/profile Description
pluginProblem.css styling for plugin errors profileSelection.css styling for the profile selector
/mozapps/update Description /mozapps/viewsource Description
updates.css styling for the browser updater viewsource.css styling for the source viewer

Developer Tools (applies only to Pale Moon 27)

/global/devtools Description /global/devtools Description
animationinspector.css styling for the animation inspector panel netmonitor.css styling for the network monitor panel
canvasdebugger.css styling for the canvas debugger panel performance.css styling for the performance watcher panel
commandline.css styling for the GCLI developer toolbar (Shift + F2) profiler.css styling for the profiler panel
common.css common styling for developer tools ruleview.css styling for rules view
computedview.css styling for computed view tab scratchpad.css styling for the JS Scratchpad
dark-theme.css styling for the developer tools when using the dark theme shadereditor.css styling for the shader editor
debugger.css styling for the debugger panel splitview.css styling for split view
eyedropper.css styling for the eyedropper storage.css styling for the storage panel
floating-scrollbars.css custom styling for the scrollbars in developer tools styleeditor.css styling for the style editor (e.g. editing CSS files)
floating-scrollbars-light.css custom styling for the scrollbars in developer tools (light theme) timeline.css styling for the timeline panel
font-inspector.css styling for the font inspector panel webaudioeditor.css styling for the web audio editor panel
inspector.css styling for inspector panel webconsole.css styling for the web console
layoutview.css styling for layout view webconsole_networkpanel.css styling for the network section of the web console
light-theme.css styling for the developer tools when using the light theme widgets.css styling for controls used in the developer tools (including icons)
markup-view.css styling for the markup view
/global/devtools/appmanager Description /global/devtools/appmanager Description
connection-footer.css styling for app manager footer panel projects.css styling for project listing in app manager
device.css styling for device listing in app manager
help.css styling for help page of app manager /global/devtools/projecteditor Description
index.css styling for app manager page projecteditor.css styling for project editor page

App Manager (deprecated) & Project Editor are inaccessible from the UI.

Now that we've covered where particular styles are kept, let's get on with the creation, shall we?

Making your theme

When making your theme, be sure to have an idea in mind already for what you want the end result to look like, so you know what you're making. It may also help to do what is most likely the easier part of theme creation first: creating your images. As was stated earlier about CSS, you don't need to remake all the images. Most theme authors will change only the toolbar images (/browser/Toolbar.png and /browser/Toolbar-inverted.png), with maybe a few other additional icons changed in /global/icons. Icons in Toolbar.png are by default 18x18px, though you can use larger icons if you change the image region scanned by the theme (using the -moz-image-region property).

With the images out of the way, make your way to /browser/browser.css and start making your theme come to life.

  background: red;

Note that most times, RGB(A)/HSL(A) values are used instead of worded names, to be able to use a precise shade.

If you're finished here, and you're satisfied with the result, then you can start to distribute it.

Packaging your theme

You've done all the hard work and now just want to get it out to people; thankfully, this is quite simple in comparison!

To package a theme for release, place everything into a .zip file, and simply rename the extension to .xpi. Assuming both install.rdf and chrome.manifest were entered correctly, your theme will now install and you can freely distribute it. If you wish to distribute it in an official manner, on the Pale Moon Add-Ons Site, then please see the relevant page relating to that.

Happy theming!

Site design and Branding © 2022 Moonchild Productions - All rights reserved
Any other content, brand names or logos are copyright or trademark to their respective owners.
Policies: Cookies - User Content - Privacy.

The Pale Moon Developer Site is powered by Project Selene 1.2.1.