Jonathan Hooverman edited this page Dec 13, 2015 · 13 revisions

Available pages:

Clone this wiki locally


To create a theme for QupZilla you will need a basic knowledge of using css styles. If you have already designed html pages with css, you will be just fine. You will achieve much better results by using Qt stylesheets. Here, you will also need some basic C++ knowledge.
There are, although, some differences between html stylesheets and Qt stylesheets.

For more information about Qt stylesheets, please see reference and examples.

Finding type of element

The styling options of each element depend on their Qt type. You will find it in the source code.


SiteIcon::SiteIcon(LocationBar* parent)
   : ToolButton(parent)

The element SiteIcon inherits its properties from ToolButton. If you look at toolbutton.h, you will see, that ToolButton inherits its properties from QToolButton.

Using qproperty-*** properties

In addition to the properties found in the documentation, you may use also internal Qt properties and even some QupZilla specific ones.
Take a look at QToolButton documentation. There are four properties (arrowType, autoRaise, popupMode, toolButtonStyle) and you can use them from the Qt stylesheets as qproperty-arrowType, qproperty-autoRaise, ...

Unfortunately, it is sometimes hard to find the exact syntax about how to write some Qt types in stylesheets.

QSize : 10px 10px
QString : "string"
int : 10
QIcon : url(path/to/icon.png)
QPixmap : url(path/to/pixmap.png)

Theme files

A theme must contain the main.css and files. Without these files, a theme will not be loaded and listed in Preferences -> Themes.
A theme can also contain a theme.license file for licensing and a theme.png as a theme icon (preferably 32×32px). template:

Name: Name of your theme
Author: Your name
Short Description: Short description of your theme
Long Description: Long description of your theme

Please do NOT add new lines to the description.

Theme hierarchy

Look at the default themes included in QupZilla to get some basic ideas for creating themes.

Basically, it is only required to have a, theme.license and main.css file in the theme root directory. You may, or may not, put all images in a separate folder. But I encourage you to do so as it makes any further edits in the theme much easier.

Testing in QupZilla

The theme folder must be moved into the themes location (found from Menu Help -> Configuration Information -> Paths -> Themes). Your theme will now appear in the Theme list in Preferences.
From 1.6 version, themes can also be loaded from $CONFIGDIR/themes (~/.config/qupzilla/themes on Linux)

Tip: You do not have to restart QupZilla after you made some changes. Just open the Preferences and click on Apply.

Additional Themes

QupZilla comes with the following themes, that are included in the tarball and most packages

  • Breathe (Strictly uses the oxygen icon set)
  • Chrome (Chrome-like theme based on the Firefox Chromifox theme)
  • Old Default (First and only theme available until QupZilla version 1.0.0-beta4)
  • Linux Default (Uses the native widget style and some basic icons from the desktop icon set)
  • Mac (Mac-like theme based on Firefox Mac OS X theme)
  • Windows (Windows default theme, based on the Firefox Strata Aero theme)

Additionally, these themes can also be used with QupZilla

  • Cyanotype (Simple, modern blue-white theme for QupZilla)
  • Fergris (Full theme for QupZilla with own Qt style)
  • Classic Winstripe (The original Winstripe theme from 0.9, a blast from the past)
  • Australis (Based on Firefox's Australis theme and David Rosca's QupZilla Chrome theme)
  • Dark Australis (Based on Firefox's Australis theme and David Rosca's QupZilla Chrome theme
  • Plasma (Based on Linux Default, with a few minor changes to make it more Plasma integrated)