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 UTF8 encoding.

The index.theme file must starts 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
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 size of the icons in this directory. integerYES
Context the context the icon is normally used in. This can be used to e.g. let the user pick an specific type of icon. Currently used contexts are: Actions, Applications, Devices, FileSystems, MimeTypes. 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 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 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 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 listen in e.g. a user interface. localestringNO
EmbeddedTextRectangle If this exist it specifies the four corners of a rectangle where the program displaying the icon can embedd 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 for 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.