1---
2title: Semantic Tokens and Syntax Highlighting - Zed
3description: Enable and configure semantic token highlighting in Zed for richer, language-server-aware syntax coloring.
4---
5
6# Semantic Tokens
7
8Semantic tokens provide richer syntax highlighting by using information from language servers. Unlike tree-sitter highlighting, which is based purely on syntax, semantic tokens understand the meaning of your code—distinguishing between local variables and parameters, or between a class definition and a class reference.
9
10## Enabling Semantic Tokens
11
12Semantic tokens are controlled by the `semantic_tokens` setting. By default, semantic tokens are disabled.
13
14```json [settings]
15{
16 "semantic_tokens": "combined"
17}
18```
19
20This setting accepts three values:
21
22| Value | Description |
23| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
24| `"off"` | Do not request semantic tokens from language servers. Uses tree-sitter highlighting only. (Default) |
25| `"combined"` | Use LSP semantic tokens together with tree-sitter highlighting. Tree-sitter provides base highlighting, and semantic tokens overlay additional information. |
26| `"full"` | Use LSP semantic tokens exclusively. Tree-sitter highlighting is disabled entirely for buffers with semantic token support. |
27
28You can configure this globally or per-language:
29
30```json [settings]
31{
32 "semantic_tokens": "off",
33 "languages": {
34 "Rust": {
35 "semantic_tokens": "combined"
36 },
37 "TypeScript": {
38 "semantic_tokens": "full"
39 }
40 }
41}
42```
43
44> **Note:** Changing the `semantic_tokens` mode may require a language server restart to take effect. Use the `lsp: restart language servers` command from the command palette if highlighting doesn't update immediately.
45
46## Customizing Token Colors
47
48Semantic tokens are styled using rules that map LSP token types and modifiers to theme styles or custom colors. Zed provides sensible defaults, but you can customize these in your settings.json: add rules under `global_lsp_settings.semantic_token_rules` key.
49
50Rules are matched in order, and the first matching rule wins.
51User-defined rules take precedence over defaults.
52
53### Rule Structure
54
55Each rule can specify:
56
57| Property | Description |
58| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
59| `token_type` | The LSP semantic token type to match (e.g., `"variable"`, `"function"`, `"class"`). If omitted, matches all types. |
60| `token_modifiers` | A list of modifiers that must all be present (e.g., `["declaration"]`, `["readonly", "static"]`). |
61| `style` | A list of theme style names to try. The first one found in the current theme is used. |
62| `foreground_color` | Override foreground color in hex format (e.g., `"#ff0000"`). |
63| `background_color` | Override background color in hex format. |
64| `underline` | Boolean or hex color. If `true`, underlines with the text color. |
65| `strikethrough` | Boolean or hex color. If `true`, strikes through with the text color. |
66| `font_weight` | `"normal"` or `"bold"`. |
67| `font_style` | `"normal"` or `"italic"`. |
68
69### Example: Highlighting Unresolved References
70
71To make unresolved references stand out:
72
73```json [settings]
74{
75 "global_lsp_settings": {
76 "semantic_token_rules": [
77 {
78 "token_type": "unresolvedReference",
79 "foreground_color": "#c93f3f",
80 "font_weight": "bold"
81 }
82 ]
83 }
84}
85```
86
87### Example: Highlighting Unsafe Code
88
89To highlight unsafe operations in Rust:
90
91```json [settings]
92{
93 "global_lsp_settings": {
94 "semantic_token_rules": [
95 {
96 "token_type": "punctuation",
97 "token_modifiers": ["unsafe"],
98 "foreground_color": "#AA1111",
99 "font_weight": "bold"
100 }
101 ]
102 }
103}
104```
105
106### Example: Using Theme Styles
107
108Instead of hardcoding colors, reference styles from your theme:
109
110```json [settings]
111{
112 "global_lsp_settings": {
113 "semantic_token_rules": [
114 {
115 "token_type": "variable",
116 "token_modifiers": ["mutable"],
117 "style": ["variable.mutable", "variable"]
118 }
119 ]
120 }
121}
122```
123
124The first style found in the current theme is used, providing fallback options.
125
126### Example: Disabling a Token Type
127
128To disable highlighting for a specific token type, add an empty rule that matches it:
129
130```json [settings]
131{
132 "global_lsp_settings": {
133 "semantic_token_rules": [
134 {
135 "token_type": "comment"
136 }
137 ]
138 }
139}
140```
141
142Since user rules are prepended to defaults and the first match wins, this empty rule prevents any styling from being applied to comment tokens.
143
144## Default Rules
145
146Zed's default semantic token rules map standard LSP token types to common theme styles. For example:
147
148- `function` → `function` style
149- `variable` with `constant` modifier → `constant` style
150- `class` → `type.class`, `class`, or `type` style (first found)
151- `comment` with `documentation` modifier → `comment.documentation` or `comment.doc` style
152
153The full default configuration can be shown in Zed with the `zed: show default semantic token rules` command.
154
155## Standard Token Types
156
157Language servers report tokens using standardized types. Common types include:
158
159| Type | Description |
160| --------------- | ---------------------------------- |
161| `namespace` | Namespace or module names |
162| `type` | Type names |
163| `class` | Class names |
164| `enum` | Enum type names |
165| `interface` | Interface names |
166| `struct` | Struct names |
167| `typeParameter` | Generic type parameters |
168| `parameter` | Function/method parameters |
169| `variable` | Variable names |
170| `property` | Object properties or struct fields |
171| `enumMember` | Enum variants |
172| `function` | Function names |
173| `method` | Method names |
174| `macro` | Macro names |
175| `keyword` | Language keywords |
176| `comment` | Comments |
177| `string` | String literals |
178| `number` | Numeric literals |
179| `operator` | Operators |
180
181Common modifiers include: `declaration`, `definition`, `readonly`, `static`, `deprecated`, `async`, `documentation`, `defaultLibrary`, and language-specific modifiers like `unsafe` (Rust) or `abstract` (TypeScript).
182
183For the complete specification, see the [LSP Semantic Tokens documentation](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#semanticTokenTypes).
184
185## Inspecting Semantic Tokens
186
187To see semantic tokens applied to your code in real-time, use the `dev: open highlights tree view` command from the command palette. This opens a panel showing all highlights (including semantic tokens) for the current buffer, making it easier to understand which tokens are being applied and debug your custom rules.
188
189## Troubleshooting
190
191### Semantic highlighting not appearing
192
1931. Ensure `semantic_tokens` is set to `"combined"` or `"full"` for the language
1942. Verify the language server supports semantic tokens (not all do)
1953. Try restarting the language server with `lsp: restart language servers`
1964. Check the LSP logs (`workspace: open lsp log`) for errors
197
198### Colors not updating after changing settings
199
200Changes to `semantic_tokens` mode may require a language server restart. Use `lsp: restart language servers` from the command palette.
201
202### Theme styles not being applied
203
204Ensure the style names in your rules match styles defined in your theme. The `style` array provides fallback options—if the first style isn't found, Zed tries the next one.