Creating Themes

This document is a brief guide to creating themes for use with NetSurf and packaging them with NSTheme. It is split up into the following sections:

Last updated 22 March 2005


A theme contains a set of sprites for NetSurf's toolbar icons and some further information about the theme, such as the background colour of the toolbar and the theme name. NSTheme is an application that loads the sprites, allows the additional information to be set and then packages the theme into a single file for distribution.


A theme contains a number of sprites; two for each button, a single separator sprite and extra sprites for the throbber animation. These sprites are to be grouped into a single sprite file and each sprite must be given a certain name, so that they can be attributed to the correct button.

The toolbar buttons and the matching sprite names are listed below.

Browser Window
ButtonSprite name
Scale Viewscale
Search / Find Textsearch
Hotlist Window
ButtonSprite name
Create Directorycreate
Delete Selectiondelete
Launch Selectionlaunch
Open Directoryopen
Expand Addressesexpand
Global History Window
ButtonSprite name
Delete Selectiondelete
Launch Selectionlaunch
Open Directoryopen
Expand Addressesexpand

Each button has a sprite for its pressed and unpressed states. The pressed sprites are preceded with the letter 'p'. For the Save button, there will be both 'save' and 'psave' sprites.

A sprite named 'separator' is used to separate groups of icons on the toolbar and the throbber is made up of any number of sprites named 'throbber0' to 'throbberN'. When NetSurf is inactive, 'throbber0' is displayed and when it is active, the throbber animation loops through 'throbber1' to 'throbberN'.

For a five frame animation, there would be five sprites named 'throbber1' to 'throbber5' plus the inactive sprite, 'throbber0'.

The sprites can have any dimensions and if some sprites are larger than others, NetSurf will centre the smaller ones on the toolbar automatically.

Using NSTheme

NSTheme's user interface should be fairly self explanatory and interactive help is available throughout the application. An existing theme can be loaded by dragging it to the NSTheme window. To create a new theme, drag a sprite file to NSTheme. Theme name and author information can be entered or altered with writable icons.

Tick "Left align throbber" if you want the throbber to appear at the left of the toolbar. If un-ticked, the throbber will be displayed at the right. If your throbber animation uses a mask that moves from frame to frame, tick "Redraw every frame", which clears the previous frame of amimation before plotting the new one on top. Leave "Redraw every frame" un-ticked if the throbber doesn't feature a moving mask as this feature can make the throbber flicker while it animates.

The Generate report button warns of any problems with the theme. For example, if no sprites have been loaded it will report, "No sprite file present". If a sprite file is loaded but the pressed Save button is missing, it will report, "Sprite 'psave' (browser save icon (pushed)) is missing". The Remove sprites button removes any sprites that had been loaded into the program.

Sprites can be extracted from an existing theme with the Export option on the NSTheme window menu. When creating a new theme it may be helpful to extract the sprite file from the supplied theme (!NetSurf.Resources.Theme) and replace these sprites with your own.

In the colours section, the background colours for the browser window toolbar, the hotlist toolbar and the browser window's status bar can be configured, along with the colour of text displayed in the status bar.

To save a finished theme, use the save option in the NSTheme window menu. Once a theme file has been created, it must be placed in Choices:WWW.NetSurf.Themes to be found by NetSurf.


Completed themes can be submitted for inclusion on NetSurf's themes page. They are served as Content-Type: application/x-netsurf-theme which NetSurf recognizes and installs as themes.