CSS Class Lens
Cmd/Ctrl-click a CSS class in an HTML file and jump straight to where that class is
defined in your stylesheets — no manual searching, no leaving the file.
What it does
- Registers a Go to Definition provider for HTML documents.
- When you Cmd-click (macOS) / Ctrl-click (Windows/Linux) a class inside a
class="..." (or className="...") attribute, it resolves that class to its selector
definitions in .css / .scss files.
- If several definitions exist, they are returned nearest-first by directory
proximity to the file you clicked from, so local styles win over distant ones.
- Because it uses the native definition API, multiple matches open in VS Code's peek
view with the surrounding rule shown inline — you see the actual style block, not
just a filename.
- Hover a class for a lightweight info panel: the definition count, clickable file
paths (nearest first), and a hint to Cmd/Ctrl-click for the editable peek. It
complements the peek rather than duplicating the CSS.
- Find All References (
⇧⌥F12) opens VS Code's native References panel with every
markup usage of the class, plus its stylesheet declarations. Works whether you invoke
it on a class in HTML or on a .class selector in a stylesheet.
- CodeLens counts above each class in markup show how many stylesheet definitions it
has (
no definition flags likely typos). Click a count to peek the definitions.
- Undefined-class diagnostics (opt-in) warn about classes used in markup that have no
stylesheet definition.
Everything is served from a single cached, watcher-backed index — definitions, hover,
references and counts all read from it, so there's no per-lookup workspace scan.
Everything is read-only: the extension only reads the workspace and hands locations
back to the editor. It never edits, moves, or writes files.
Settings
| Setting |
Default |
Description |
cssClassLens.enabled |
true |
Toggle the go-to-definition provider. |
cssClassLens.showHover |
true |
Show the class hover panel (count, file paths, peek hint). |
cssClassLens.showCodeLens |
true |
Show definition-count CodeLens above classes in markup. |
cssClassLens.reportUndefinedClasses |
false |
Warn about markup classes with no stylesheet definition. Off by default (library/global classes can be false positives). |
cssClassLens.definitionGlob |
**/*.{css,scss} |
Stylesheet files indexed for class definitions. |
cssClassLens.referenceGlob |
**/*.{html,htm} |
Markup files scanned for class usages in Find All References. |
cssClassLens.excludeGlob |
**/{node_modules,dist,build,out,.angular,coverage,.next}/** |
Files/folders excluded from indexing and searches. |
cssClassLens.maxFilesScanned |
2000 |
Safety cap on files scanned per lookup or index build. |
How it works
A workspace-wide index (class name -> definition locations) is built lazily on first
use and then kept fresh incrementally via a FileSystemWatcher — a changed stylesheet
only re-scans itself. Definitions, hover, references and CodeLens counts all read from
this index, so lookups are O(1) and there is no per-action workspace scan.
Matching is lexical but selector-scoped: comments, strings and url(...) are ignored,
and class tokens are only accepted in selector position. This covers the common cases
(.a.b, .btn:hover, descendant selectors, comma lists, SCSS nesting) without a full CSS
parse, while dropping false positives like .png from url(sprite.png).
Roadmap
Planned enhancements and their design are tracked in
docs/future-enhancements.md.
Development
npm install
npm run compile # tsc -> out/
npm test # runs the pure-logic unit tests
npm run install-extension # symlink into ~/.cursor/extensions, then reload window
