---

15.6 Custom Themes

Custom themes are collections of settings that can be enabled or disabled as a unit. See Custom Themes in The GNU Emacs Manual. Each Custom theme is defined by an Emacs Lisp source file, which should follow the conventions described in this section. (Instead of writing a Custom theme by hand, you can also create one using a Customize-like interface; see Creating Custom Themes in The GNU Emacs Manual.)

A Custom theme file should be named foo-theme.el, where foo is the theme name. The first Lisp form in the file should be a call to deftheme, and the last form should be a call to provide-theme.

Macro: deftheme theme &optional doc &rest properties ¶

This macro declares theme (a symbol) as the name of a Custom theme. The optional argument doc should be a string describing the theme; this is the description shown when the user invokes the describe-theme command or types ? in the ‘*Custom Themes*’ buffer. The remaining arguments properties are used pass a property list with theme attributes.

The following attributes are supported:

:family

A symbol designating what “family” a theme belongs to. A family of themes is a set of similar themes that differ by minor aspects, such as face colors that are meant for the light vs dark background of the frame.

:kind

A symbol. If a theme is enabled and this property has the value color-scheme, then the theme-choose-variant command will look for other available themes that belong to the same family in order to switch the themes. Other values are currently unspecified and should not be used.

:background-mode

A symbol, either light or dark. This attribute is currently unused, but should still be specified.

Two special theme names are disallowed (using them causes an error): user is a dummy theme that stores the user’s direct customization settings, and changed is a dummy theme that stores changes made outside of the Customize system.

Macro: provide-theme theme ¶

This macro declares that the theme named theme has been fully specified.

In between deftheme and provide-theme are Lisp forms specifying the theme settings: usually a call to custom-theme-set-variables and/or a call to custom-theme-set-faces.

Function: custom-theme-set-variables theme &rest args ¶

This function specifies the Custom theme theme’s variable settings. theme should be a symbol. Each argument in args should be a list of the form

(var expression [now [request [comment]]])

where the list entries have the same meanings as in custom-set-variables. See Applying Customizations.

Function: custom-theme-set-faces theme &rest args ¶

This function specifies the Custom theme theme’s face settings. theme should be a symbol. Each argument in args should be a list of the form

(face spec [now [comment]])

where the list entries have the same meanings as in custom-set-faces. See Applying Customizations.

In theory, a theme file can also contain other Lisp forms, which would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. As such, themes are not ordinarily byte-compiled, and source files usually take precedence when Emacs is looking for a theme to load.

The following functions are useful for programmatically enabling and disabling themes:

Function: custom-theme-p theme ¶

This function return a non-nil value if theme (a symbol) is the name of a Custom theme (i.e., a Custom theme which has been loaded into Emacs, whether or not the theme is enabled). Otherwise, it returns nil.

Variable: custom-known-themes ¶

The value of this variable is a list of themes loaded into Emacs. Each theme is represented by a Lisp symbol (the theme name). The default value of this variable is a list containing two dummy themes: (user changed). The changed theme stores settings made before any Custom themes are applied (e.g., variables set outside of Customize). The user theme stores settings the user has customized and saved. Any additional themes declared with the deftheme macro are added to the front of this list.

Command: load-theme theme &optional no-confirm no-enable ¶

This function loads the Custom theme named theme from its source file, looking for the source file in the directories specified by the variable custom-theme-load-path. See Custom Themes in The GNU Emacs Manual. It also enables the theme (unless the optional argument no-enable is non-nil), causing its variable and face settings to take effect. It prompts the user for confirmation before loading the theme, unless the optional argument no-confirm is non-nil.

Function: require-theme feature &optional noerror ¶

This function searches custom-theme-load-path for a file that provides feature and then loads it. This is like the function require (see Features), except it searches custom-theme-load-path instead of load-path (see Library Search). This can be useful in Custom themes that need to load supporting Lisp files when require is unsuitable for that.

If feature, which should be a symbol, is not already present in the current Emacs session according to featurep, then require-theme searches for a file named feature with an added ‘.elc’ or ‘.el’ suffix, in that order, in the directories specified by custom-theme-load-path.

If a file providing feature is successfully found and loaded, then require-theme returns feature. The optional argument noerror determines what happens if the search or loading fails. If it is nil, the function signals an error; otherwise, it returns nil. If the file loads successfully but does not provide feature, then require-theme signals an error; this cannot be suppressed.

Command: enable-theme theme ¶

This function enables the Custom theme named theme. It signals an error if no such theme has been loaded.

Command: disable-theme theme ¶

This function disables the Custom theme named theme. The theme remains loaded, so that a subsequent call to enable-theme will re-enable it.