File Formats

Both the icon theme description file and the icon data files are ini-style text files, as described in the desktop file specification. They don't have any encoding field. Instead, they must always be stored in UTF-8 encoding.

The index.theme file must start with a section called Icon Theme, with contents according to table 1 below. All lists are comma-separated.

Table 1. Standard Keys

KeyDescriptionValue TypeRequired
Name short name of the icon theme, used in e.g. lists when selecting themes. localestringYES
Comment longer string describing the theme localestringYES
Inherits

The name of the theme that this theme inherits from. If an icon name is not found in the current theme, it is searched for in the inherited theme (and recursively in all the inherited themes).

If no theme is specified implementations are required to add the "hicolor" theme to the inheritance tree. An implementation may optionally add other default themes in between the last specified theme and the hicolor theme.

stringsNO
Directories list of subdirectories for this theme. For every subdirectory there must be a section in the index.theme file describing that directory. stringsYES
ScaledDirectories Additional list of subdirectories for this theme, in addition to the ones in Directories. These directories should only be read by implementations supporting scaled directories and was added to keep compatibility with old implementations that don't support these. stringsNO
Hidden Whether to hide the theme in a theme selection user interface. This is used for things such as fallback-themes that are not supposed to be visible to the user. booleanNO
Example The name of an icon that should be used as an example of how this theme looks. stringNO


Each directory specified in the Directory key has a corresponding section with the same name as the directory. The contents of this section is listed in table 2 below.

Table 2. Per-Directory Keys

KeyDescriptionValue TypeRequiredType
Size Nominal (unscaled) size of the icons in this directory. integerYES
Scale Target scale of of the icons in this directory. Defaults to the value 1 if not present. Any directory with a scale other than 1 should be listed in the ScaledDirectories list rather than Directories for backwards compatibility. integerNO
Context The context the icon is normally used in. This is in detail discussed in the section called “Context”. stringNO
Type The type of icon sizes for the icons in this directory. Valid types are Fixed, Scalable and Threshold. The type decides what other keys in the section are used. If not specified, the default is Threshold. stringNO
MaxSize Specifies the maximum (unscaled) size that the icons in this directory can be scaled to. Defaults to the value of Size if not present. integerNOScalable
MinSize Specifies the minimum (unscaled) size that the icons in this directory can be scaled to. Defaults to the value of Size if not present. integerNOScalable
Threshold The icons in this directory can be used if the size differ at most this much from the desired (unscaled) size. Defaults to 2 if not present. integerNOThreshold


In addition to these groups you may add extra groups to the index.theme file in order to extend it. These extensions must begin with "X-", and can be used to add desktop specific information to the theme file. Example group names would be "X-KDE Icon Theme" or "X-Gnome Icon Theme".

The optional filename.icon file contains a group called "Icon Data", with the content listed in table 3.

Table 3. Icon Data Keys

KeyDescriptionValue TypeRequired
DisplayName A translated UTF8 string that can be used instead of the icon name when the icon is listed in e.g. a user interface. localestringNO
EmbeddedTextRectangle If this exists, it specifies the four corners of a rectangle where the program displaying the icon can embed text. This is normally used by e.g. file managers that want to display a preview of text file contents in the icon. The corners are specified by a list of four values: x0,y0,x1,y1. The values are pixel coordinates from the top left corner of the icon, except for SVG files, where they are specified in a 1000x1000 coordinate space that is scaled to the final rendered size of the icon. integersNO
AttachPoints A list of points, separated by "|" that may be used as anchor points for emblems/overlays. The points are pixel coordinates from the top left corner of the icon, except for SVG files, where they are specified in a 1000x1000 coordinate space that is scaled to the final rendered size of the icon. pointsNO


Extensions to the filename.icon file are allowed, but the keys must be begin with "X-" to avoid collisions with future standardized extensions to this format.

Context

The Context allows the designer to group icons on a conceptual level. It doesn't act as a namespace in the file system, such that icons can have identical names, but allows implementations to categorize and sort by it, for example.

These are the available contexts:

  • Actions. Icons representing actions which the user initiates, such as Save As.

  • Devices. Icons representing real world devices, such as printers and mice. It's not for file system nodes such as character or block devices.

  • FileSystems. Icons for objects which are represented as part of the file system. This is for example, the local network, Home, and Desktop folders.

  • MimeTypes. Icons representing MIME types.