Documentation Themes

The look of the Sublime Text interface is controlled by themes. The term theme refers strictly to the look of the UI – buttons, select lists, the sidebar, tabs and so forth. The highlighting of source code, markup and prose is controlled by a color scheme.

The theme engine for Sublime Text is based on raster graphics. PNGs are used to prevent texture degradation and provide full alpha control. Each element in the UI can have up to four layers of textures or fills applied, with properties to control opacity and padding. The properties set on each element can be conditionally changed based on user interaction and settings.

Sublime Text themes are implemented via the .sublime-theme format. It is a JSON format that specifies rules for matching elements and modifying their appearance.

Example

The following is an example of the format of a .sublime-theme file. A complete theme will have many more rules to cover all elements used in the UI.

{
    // Set up the textures for a button
    {
        "class": "button_control",
        "layer0.tint": [0, 0, 0],
        "layer0.opacity": 1.0,
        "layer1.texture": "Theme - Example/textures/button_background.png",
        "layer1.inner_margin": 4,
        "layer1.opacity": 1.0,
        "layer2.texture": "Theme - Example/textures/button_highlight.png",
        "layer2.inner_margin": 4,
        "layer2.opacity": 0.0,
        "content_margin": [4, 8, 4, 8]
    },
    // Show the highlight texture when the button is hovered
    {
        "class": "button_control",
        "attributes": ["hover"],
        "layer2.opacity": 1.0
    },
    // Basic text label style
    {
        "class": "label_control",
        "fg": [240, 240, 240],
        "font.bold": true
    },
    // Brighten labels contained in a button on hover
    {
        "class": "label_control",
        "parents": [{"class": "button_control", "attributes": ["hover"]}],
        "fg": [255, 255, 255]
    }
}

Terminology

A theme is a JSON array of objects, called rules. Each rule object contains a class key used to match to an element. In addition to the class, matching can be further restricted by specifying attributes, settings, parents and platforms keys. Properties affect the look or behavior of the element.

Most elements have a single class name, although a few have more than one to allow for both generic, and specific styling. For example, the popup_control class can be used to set styles for the auto complete and HTML popups, however popup_control auto_complete_popup may be used to target just the auto complete popup. Multiple class values are separated by a space. When a rule specified multiple class names, all must be present on the element for the rule to be applied.

attributes are set by Sublime Text, and indicate the state of user interaction, or other information about the nature of an element. The value is an array of strings. Examples include "hover", "pressed" and "dirty".

settings are user-controlled values that can be changed at run-time. The value is an array of strings which are the names of boolean settings pulled from .sublime-settings files. To check for a false value, prefix the setting name with a ! Themes may also create their own settings to allow users to change the style. Examples include "bold_folder_labels" and "!always_show_minimap_viewport".

The parents key is an array of objects specifying the class and attributes that must be matched in a parent element.

The platforms key is an array of strings specifying the what operating systems to apply the rule to. Valid options include "osx", "windows", and "linux".

Properties refer to all other keys in the JSON objects. Some properties are available on all elements, while others are specific to an individual element.

General Information

The follow sections discuss information about images and how to specify styles.

Specificity

Unlike CSS, a Sublime Text theme does not do specificity matching when applying rules to elements. All rules are tested, in order, against each element. Subsequent rules that match will override properties from previous rules.

Texture Images

All textures in a theme are specified using PNG images. Each texture should be saved at "normal" DPI, where each pixel in the file will be mapped to one device pixel. All file paths in the theme definition should reference the normal DPI version.

A second version of each texture should also be included at double the DPI, with @2x added to the filename right before the extension. Sublime Text will automatically use the @2x version when being displayed on a high-DPI screen.

Although currently not implemented, the increasing resolution of displays will likely result in support for @3x variants at some point in the future.

SVG images are not currently supported.

Dimensions

Integer units in a theme referring to dimensions are always specified in device-independent pixels (DIP). Sublime Text automatically handles scaling UI elements based on the screen density.

Padding & Margins

Padding and margin may be specified in one of three ways:

  • A single integer value – the same value is applied to the left, top, right and bottom
  • An array of two integers – the first value is applied to the left and top, while the second value is applied to the right and bottom
  • An array of four integers – the values are applied, in order, to the left, top, right and bottom

Color Values

Colors may be specified in a number of different formats:

RGB

Colors in the RGB color space are specified via an array of 3 or 4 numbers, with the first three being integers ranging from 0 to 255 representing the components red, green and blue. The optional fourth number is a float ranging from 0.0 to 1.0 that controls the opacity of the color.

The color white, with full opacity

[255, 255, 255]

The color blue, with 50% opacity

[0, 0, 255, 0.5]

HSL

Colors may also be specified using the HSL color space by creating an array of 4 elements, with the first being the string "hsl". The second element is an integer from 0 to 360 specifying the hue. The third is an integer from 0 to 100 specifying the saturation, and the fourth is an integer from 0 to 100 specifying the lightness.

A dark magenta, with full opacity

["hsl", 325, 100, 30]

A float from 0.0 to 1.0 may be added as a fifth element to control the opacity.

A bright teal, with 50% opacity

["hsl", 180, 100, 75, 0.5]

Derived Colors

It is also possible to derive colors from the current global color scheme. Colors in this format are specified using arrays with specific formats. In all cases, the first element is the base color, which may be "foreground", "background" or "accent".

Change Opacity of Base Color

To change the opacity of a base color, specify an array of 2 elements, the first being the base color name and the second being a float from 0.0 to 1.0. The opacity will be set to the float value.

The color scheme foreground, at 90% opacity

["foreground", 0.9]
De-saturate Base Color

To de-saturate a base color, specify an array with 3 elements. The first is the name of the base color, the second is the string "grayscale", and the third is an integer from 0 to 100 which specifies what percentage of the saturation (in HSL color space) of the existing color should be retained. A value of 100 means no change, whereas a value of 0 would cause the color to be completely desaturated.

The color scheme foreground, with the saturation adjusted to 1/4 of the original value.

["foreground", "grayscale", 25]
Tint Base Color

5 and 6-element derived colors allow blending a color into the base color. A 5-element colors uses an RGBA color, whereas a 6-element uses an HSLA. In both cases, the last element, which normally represents the opacity, controls how much of the secondary color is blended into the base.

The color scheme background, lightened with white

["background", 255, 255, 255, 0.1]

The color scheme accent, tinted with dark red

["accent", "hsl", 0, 100, 30, 0.2]

Colors derived from the color scheme will always be based on the global color scheme, and will not reflect view-specific color schemes. Certain view-specific controls in the UI have tinting properties that allow using the view-specific color scheme colors.

Attributes

Attributes are specified as an array of strings. Each string is an attribute name. To check for the absence of an attribute, prepend a ! to the name.

The following attributes are common to all elements:

hover
set whenever the user's mouse is hovered over an element

Luminosity

Although not available on all elements, many have attributes set based on the approximate luminosity of the current color scheme. Most elements have the attributes set based on the global color scheme. Tabs and the tab background, however, have the attributes based on the color scheme specific to the selected view.

The attributes are assigned based on the V value of the background color, when represented as HSV colors.

file_light
V from 0.60-1.00
file_medium
V from 0.30-0.59
file_medium_dark
V from 0.10-0.29
file_dark
V from 0.00-0.09

Settings

Certain Sublime Text settings are design to influence the UI. Themes should respect these settings and change elements based on them.

overlay_scroll_bars
this should affect the style of the scroll bars – generally they should be semi-transparent and the overlay property of the scroll_area_control should be set to true
always_show_minimap_viewport
if the current viewport area should be highlighted on the minimap even when the user is not hovering over the minimap.
bold_folder_labels
if folder names in the side bar should have the font.bold property set to true.
mouse_wheel_switches_tabs
this is used to control mouse wheel behavior of tabs on Linux. It should be combined with checking for !enable_tab_scrolling to change the mouse_wheel_switch key of the tabset_control to false.
highlight_modified_tabs
if the tabs of modified files should be highlighted. This setting should be checked in addition to the dirty attribute.
show_tab_close_buttons
if tabs should have close buttons

Properties

A .sublime-theme file is a JSON array of objects describing how UI elements should be styled. Every element in the UI supports the following keys:

layer0.*
the bottom-most texture layer for the element
layer1.*
the second texture layer for the element
layer2.*
the third texture layer for the element
layer3.*
the fourth texture layer for the element
hit_test_level
a float value setting the required opacity of a pixel for a click to be considering a "hit"

Layer Properties

Every element in the UI supports up to four texture layers for displaying fill colors and raster graphics. Each layer has dotted sub-keys in the format layer#.sub-key. Valid sub-keys include:

layer#.opacity

a float value from 0.0 to 1.0 that controls the master opacity of the layer.

Example: 0.9
layer#.tint

a color value of a fill color to apply to the layer.

Example: [255, 0, 0, 127]
layer#.texture

a string of the file path to a PNG image, relative to the Packages/ folder.

Example: "Theme - Default/arrow_right.png"
layer#.inner_margin

texture images are stretched to fit the element by slicing into a grid of 9 using four lines. See padding & margins for valid formats with which to specify the margin used to make the slices.

Example: [5, 2, 5, 2]
layer#.draw_center

a boolean that controls if the center rectangle of the 9-grid created via layer#.inner_margin should be drawn. This is an optimization that allows skipping an unused section of texture.

Example: false
layer#.repeat

a boolean that controls if the texture should be repeated instead of stretched.

Example: false

Value Animation

Properties specified by floats may be animated over time. Instead of providing a single numeric value, the animation is specified with an object including details of the animation. Value animation is primarily useful for changing opacity over time. The object keys are:

target

a float value from 0.0 to 1.0 that controls the destination value

Example: 1.0
speed

a float value of 1.0 or greater that controls the relative length of time the animation takes

Example: 1.5
interpolation

an optional string that allow specifying the use of smoothstep function instead of the default linear function.

Default: "linear"
Example: "smoothstep"

Since rules are applied sequentially, it is possible to try and set a base opacity and then have a subsequent rule that specifies an attribute or parent try to apply an animation. This will often lead to the value being reset to the base amount, and then the animation seemingly not working.

Texture Animation

The layer#.texture sub-key may be an object to specify an animation based on two or more PNG images. The object keys are:

keyframes

an array of strings of the paths to PNG images, in order

Example: ["Theme - Default/spinner.png", "Theme - Default/spinner1.png"]
loop

an optional boolean that controls if the animation should repeat

Default: false
Example: true
frame_time

an optional float specifying how long each frame should be displayed. 1.0 represents 1 second.

Default: 0.0333 (30 fps)
Example: 0.0166 (60 fps)

Texture Tinting Properties

Certain elements have an available tint value set by the background of current color scheme. The tint can be modified and applied to a layer#.texture image.

tint_index

Controls which layer the tint is applied to. Must be an integer from 0 to 3.

tint_modifier

An array of four integers in the range 0 to 255. The first three are blended into the RGB values from the tint color with the fourth value specifying how much of these RGB modifier values to apply.

Font Properties

Certain textual elements allow setting the following font properties:

font.face
the name of the font face
font.size
an integer point size
font.bold
a boolean, if the font should be bold
font.italic
a boolean, if the font should be italic

Shadow Properties

Some text elements allow setting the following properties:

shadow_color
a color value to use for the text shadow
shadow_offset
a 2-element array containing the X and Y offsets of the shadow

Filter Label Properties

Labels used in the quick panel have color control based on selection and matching

fg
a color value for unselected, unmatched text
match_fg
a color value for unselected, matched text
bg
a color value for the background of an unselected row
selected_fg
a color value for selected, unmatched text
selected_match_fg
a color value for selected, matched text
bg
a color value for the background of a selected row
font.face
the name of the font face
font.size
an integer point size

Data Table Properties

Row-based tables of data provide the following properties:

dark_content
if the background is dark – used to set the dark attribute for scrollbars
row_padding
padding added to each row, in one of the formats described in padding & margins

Elements

The following is an exhaustive list of the elements that comprise the Sublime Text UI, along with supported attributes and properties.

Windows

title_bar

Only supported on OS X 10.10+.

Attributes

luminosity attributes

Properties

fg
a color value to use for the window title text
bg
a color value to use for the title bar background
window

This element can not be styled directly, however it can be used in a parents specifier. The luminosity attributes are set based on the global color scheme.

Attributes

luminosity attributes

Properties

none
edit_window

This element contains the main editor window, and is intended for use in a parents specifier.

Properties

none
switch_project_window

This element contains the Switch Project window, and is intended for use in a parents specifier.

Properties

none

Side Bar

sidebar_container

The primary sidebar container that handles scrolling

Properties

content_margin
the margin around the sidebar_tree
sidebar_tree

A tree control containing multiple tree_rows

Properties

data table properties
indent
an integer amount to indent each level of the tree structure
indent_offset
an additional indent applied to every row, for the sake of positioning disclosure_button_control and close_button
indent_top_level
a boolean if top-level rows in the tree should be indented
spacer_rows
a boolean controlling if a blank row should be added between the Open Files and Folders sections of the sidebar, when both are visible.
tree_row

A row may contain a header, open file, folder or file

Attributes

selectable
when a row is selectable
selected
when an selectable row is selected
expandable
when a row is expandable
expanded
when an expandable row is expanded
sidebar_heading

One of the "Open Files", "Group #" or "Folders" headings in the sidebar

Properties

font properties shadow properties
fg
a color value to use for the text
sidebar_label

Names of open files, folder names and filenames

Properties

font properties shadow properties
fg
a color value to use for the text
close_button

A button to the left of each file in the Open Files section

Properties

content_margin
for buttons, the margin specifies the dimensions
disclosure_button_control

An expand/collapse icon present in all tree_rows that can be expanded

Properties

content_margin
for buttons, the margin specifies the dimensions
icon_folder

Used for a folder once the contents have been fully enumerated

Properties

content_margin
for icons, the margin specifies the dimensions
icon_folder_loading

Used for a folder while the contents are being enumerated

Properties

content_margin
for icons, the margin specifies the dimensions
icon_folder_dup

Used for a folder that has been scanned previously in the sidebar. This is necessary to prevent a possibly infinite list of files due to recursive symlinks.

Properties

content_margin
for icons, the margin specifies the dimensions
icon_file_type

The icon for a file. The layer0.texture should not be set since it is determined dynamically based on the icon setting provided by .tmPreferences files.

Properties

content_margin
for icons, the margin specifies the dimensions

Tabs

tabset_control

Attributes

luminosity attributes

Properties

content_margin
the margin around the tab_controls
tab_overlap
how many DIPs the tabs should overlap
tab_width
default tab width when space is available
tab_min_width
the minimum tab width before tab scrolling occurs
tab_height
the height of the tabs in DIPs
mouse_wheel_switch
if the mouse wheel should switch tabs – this should only be set to true if the setting enable_tab_scrolling is false
tab_control

Attributes

luminosity attributes
dirty
when the associated view has unsaved changed
selected
when the associated view is the active view in its group
transient
when the associate view is a preview and not fully opened

Properties

content_margin
the margin around the tab_label
max_margin_trim
how much of the left and right content_margin may be removed when tab space is extremely limited
accent_tint_index

Controls which layer the accent tint is applied to. Must be an integer from 0 to 3. The accent color is specified by the color scheme.

accent_tint_modifier

An array of four integers in the range 0 to 255. The first three are blended into the RGB values from the accent tint color with the fourth value specifying how much of these RGB modifier values to apply.

tab_label

Attributes

transient
when the associate view is a preview and not fully opened

Properties

font properties shadow properties
fg
a color value to use for the text
tab_close_button

Properties

content_margin
for buttons, the margin specifies the dimensions
accent_tint_index

Controls which layer the accent tint is applied to. Must be an integer from 0 to 3. The accent color is specified by the color scheme.

accent_tint_modifier

An array of four integers in the range 0 to 255. The first three are blended into the RGB values from the accent tint color with the fourth value specifying how much of these RGB modifier values to apply.

scroll_tabs_left_button

Properties

content_margin
for buttons, the margin specifies the dimensions
scroll_tabs_right_button

Properties

content_margin
for buttons, the margin specifies the dimensions
show_tabs_dropdown_button

Properties

content_margin
for buttons, the margin specifies the dimensions

Quick Panel

The quick panel is used for the various Goto functionality, the command palette and is available for use by plugins.

overlay_control

The container for the quick panel, including the input and data table

Properties

content_margin
the margin around the quick_panel
quick_panel

The data table displayed below the input. Normally the height is dynamic so the layers will not be visible, however the Switch Project window will use layers for the blank space below the filtered options.

Properties

data table properties
mini_quick_panel_row

A non-file row in quick_panel. Contains one quick_panel_label for each line of text in the row.

Attributes

selected
when the row is selected
quick_panel_row

A Goto Anything file row in quick_panel. Also used in the Switch Project window.

Contains quick_panel_label with the filename, and quick_panel_path_label for the file path.

Attributes

selected
when the row is selected
quick_panel_label

Filenames in quick_panel_row and all text in mini_quick_panel_row

Properties

filter label properties
quick_panel_path_label

File paths in quick_panel_row

Properties

filter label properties

Views

text_area_control

This element can not be styled directly since that is controlled by the color scheme, however it can be used in a parents specifier.

Attributes

luminosity attributes

Properties

none
grid_layout_control

The borders displayed between views when multiple groups are visible

Properties

no layer support
border_color
a color value to use for the border
border_size
an integer of the border size in DIPs
minimap_control

Control over the display of the viewport projection on the minimap

Properties

no layer support
viewport_color
a color value to fill the viewport projection with
viewport_opacity
a float from 0.0 to 1.0 specifying the opacity of the viewport projection
fold_button_control

Code folding buttons in the gutter

Attributes

expanded
when a section of code is unfolded

Properties

content_margin
for buttons, the margin specifies the dimensions
popup_control auto_complete_popup

The primary container for the auto complete popup

popup_control html_popup

The primary container for the HTML popups used by Show Definitions and third-party packages. The tint of the scroll bar will be set to the background color of the HTML document.

auto_complete

The data table for completion data. The tint is set based on the background color of the color scheme applied to the view the popup is displayed in.

Properties

data table properties texture tinting properties
table_row

A row in auto_complete

Attributes

selected
when the user has highlighted a completion
auto_complete_label

Text in a table_row

Properties

filter label properties
fg_blend
a boolean controlling if the fg, match_fg, selected_fg, and selected_match_fg values should be blended onto the foreground color from the color scheme of the current view

Panels

panel_control find_panel

The container for the Find and Incremental Find panels.

Properties

content_margin
the margin around the panel contents
panel_control replace_panel

The container for the Replace panel.

Properties

content_margin
the margin around the panel contents
panel_control find_in_files_panel

The container for the Find in Files panel.

Properties

content_margin
the margin around the panel contents
panel_control input_panel

The container for the input panel, which is available via the API and used for things like file renaming.

Properties

content_margin
the margin around the panel contents
panel_control console_panel

The container for the Console.

Properties

content_margin
the margin around the panel contents
panel_control output_panel

The container for the output panel, which is available via the API and used for build results.

Properties

content_margin
the margin around the panel contents
panel_control switch_project_panel

The container for the input in the Switch Project window.

Properties

content_margin
the margin around the panel contents
panel_grid_control

The layout grid used to position inputs on the various panels.

Properties

no layer support
inside_spacing
an integer padding to place between each cell of the grid
outside_vspacing
an integer padding to place above and below the grid
outside_hspacing
an integer padding to place to the left and right of the grid
panel_close_button

The button to close the open panel

Properties

content_margin
for buttons, the margin specifies the dimensions

Status Bar

status_bar

Attributes

panel_visible
when a panel is displayed above the status bar

Properties

content_margin
the margin around the panel_button_control, status_container and status_buttonss
panel_button_control

The panel switcher button on the left side of the status bar

Properties

content_margin
for buttons, the margin specifies the dimensions
status_container

The area that contains the current status message

Properties

content_margin
the margin around the status message
status_button

The status buttons that display, and allow changing, the indentation, syntax, encoding and line endings

Properties

content_margin
for buttons, the margin specifies the dimensions
min_size
an array of two integers specifying the minimum width and height of a button, in DIPs

Dialogs

dialog

The Indexer Status and Update windows both use this class for the window background

progress_bar_control

The progress bar container. The progress bar is displayed in the Update window used for updates on OS X and Windows.

progress_gauge_control

The bar representing the progress completed so far

Properties

content_margin
the margin specifies the height of the bar

Scroll Bars

scroll_area_control

The scroll area contains the element being scrolled, along with the bar, track and puck.

Properties

content_margin
a margin that is added around the content being scrolled
overlay
sets the scroll bars to be rendered on top of the content
scroll_bar_control

The scroll bar contains the scroll track. The tint is set based on the background color of the element being scrolled.

Attributes

dark
when the scroll area content is dark, necessitating a light scroll bar
horizontal
when the scroll bar should be horizontal instead of vertical

Properties

texture tinting properties
content_margin
a margin that is added around the scroll track
scroll_track_control

The track that the puck runs along. The tint is set based on the background color of the element being scrolled.

Attributes

dark
when the scroll area content is dark, necessitating a light scroll bar
horizontal
when the scroll bar should be horizontal instead of vertical

Properties

texture tinting properties
scroll_corner_control
puck_control

The scroll puck, or handle. The tint is set based on the background color of the element being scrolled.

Attributes

dark
when the scroll area content is dark, necessitating a light scroll bar
horizontal
when the scroll bar should be horizontal instead of vertical

Properties

texture tinting properties

Inputs

text_line_control

The text input used by the Quick Panel, Find, Replace, Find in Files and Input panels.

Properties

content_margin
the margin around the text
color_scheme_tint
a color value to use to tint the background of the color scheme
color_scheme_tint_2
a color value to use to add a secondary tint to the background of the color scheme
dropdown_button_control

The button to close the open panel

Properties

content_margin
for buttons, the margin specifies the dimensions

Buttons

button_control

Text buttons

Attributes

pressed
set when a button is pressed down

Properties

min_size
an array of two integers specifying the minimum width and height of a button, in DIPs
icon_button_group

A grid controlling the spacing of related icon buttons

Properties

no layer support
spacing
an integer number of pixels between each button in the group
icon_button_control

Small icon-based buttons in the Find, Find in Files, and Replace panels

Attributes

selected
when an icon button is toggled on
left
when the button is the left-most button in a group
right
when the button is the right-most button in a group
icon_regex

The button to enable regex mode in the Find, Find in Files and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_case

The button to enable case-sensitive mode in the Find, Find in Files and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_whole_word

The button to enable whole-word mode in the Find, Find in Files and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_wrap

The button to enable search wrapping when using the Find and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_in_selection

The button to only search in the selection when using the Find and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_highlight

The button to enable highlighting all matches in the Find and Replace panels

Properties

content_margin
for icons, the margin specifies the dimensions
icon_preserve_case

The button to enable preserve-case mode when using the Replace panel

Properties

content_margin
for icons, the margin specifies the dimensions
icon_context

The button to show context around matches when using the Find in Files panel

Properties

content_margin
for icons, the margin specifies the dimensions
icon_use_buffer

The button to display results in a buffer, instead of an output panel, when using the Find in Files panel

Properties

content_margin
for icons, the margin specifies the dimensions

Labels

label_control

Labels are shown in the Find, Replace, Find in File and Input panels. Additionally, labels are used in the Update window, on textual buttons and for the text in the status_container.

Targeting specific labels can be accomplished by using the parents key.

Properties

font properties shadow properties
color
a color value to use for the text
title_label_control

The title label is used in the About window.

Properties

font properties shadow properties
color
a color value to use for the text

Tool Tips

tool_tip_control

Tool tips shown when hovering over tabs and buttons

Properties

content_margin
the margin around the tool tip text
tool_tip_label_control

Text shown in a tool tip

Properties

font properties shadow properties
color
a color value to use for the text

Deprecated

Color Values

Before build 3127, the only way to specify opacity in colors was by using a 4-element array containing all integers from 0 to 255. The fourth element controlled the opacity, such that 0 was fully transparent and 255 was fully opaque. The preferred format is now to use a float from 0.0 to 1.0.

Obsolete

As the UI of Sublime Text has adapted over time, certain elements and properties are no longer applicable or supported.

Elements

The sheet_container_control element is never visible to users in recent versions of Sublime Text 3.

An element named icon_reverse used to exist in the find panel to control if searching would move forward or backwards in the view. This is now controlled by the Find and Find Prev buttons.

The element named quick_panel_score_label is no longer present in the Goto Anything quick panel.

Properties

The blur property used to be supported to blur the pixel data behind an element, however it is not currently supported for implementation reasons.