feat(language-service): add Document Symbols support for Angular templates by kbrilla · Pull Request #66690 · angular/angular

kbrilla · 2026-01-21T19:56:58Z

PR: feat(language-service): add Document Symbols support for Angular templates

Description

Adds comprehensive Document Symbols support for Angular templates, enabling the Outline panel, breadcrumbs navigation, and "Go to Symbol" (Cmd+Shift+O / Ctrl+Shift+O) features to work with Angular template syntax.

Features

Block Syntax Support

@if, @else, @else if with expression and alias display
@for with track expression and context variables
@switch, @case, @default blocks
@defer, @placeholder, @loading, @error blocks with triggers
@let declarations

Structural Directive Support

*ngIf, *ngFor, *ngSwitch, *ngSwitchCase, *ngSwitchDefault
*ngTemplateOutlet, *ngComponentOutlet, *ngPlural, *ngPluralCase
Custom structural directives (shown with Class icon)

Template File Support

TypeScript files: Template symbols nested under (template) node in component class
External HTML templates: Template symbols at root level (works with templateUrl)

Multi-Component Support

Multiple components per file: Correctly merges template symbols into each component class
Non-standard naming: Works with components without "Component" suffix

Variables and References

Loop item variables (let item)
Template reference variables (#ref)
Context variable aliases (let i = $index)
Expression aliases (as alias)

SymbolKind Mappings

Template Element	SymbolKind	Icon
`@if`, `@else`, `@switch`, `@case`	Struct	🔶
`@for`, `@empty`	Array	📦
`@defer`, `@placeholder`, `@loading`, `@error`	Event	⚡
HTML elements	Object	🟡
Variables	Variable
Structural directives	Class

Configuration

`angular.documentSymbols.enabled` (default: `true`)

Enables Angular-specific document symbols.

`angular.documentSymbols.showImplicitForVariables` (default: `false`)

Shows all implicit @for loop variables ($index, $count, $first, $last, $even, $odd).

Example

Template:

@for (item of items; track item.id; let i = $index) {
  @if (item.visible; as isVisible) {
    <div #container (click)="onClick()">
      {{ item.name }}
    </div>
  }
}

Outline:

@for (item of items)  📦
├── let item
├── let i
├── @if (item.visible; as isVisible)  🔶
│   ├── as isVisible
│   └── <div>  🟡
│       └── #container

Breaking Changes

None

Related Issues

Closes #66691

AI Disclosure

This PR was developed using Claude Opus 4.6 and GPT 5.3 Max AI assistants under human orchestration and review by @kbrilla.

atscott · 2026-01-21T20:54:44Z

vscode-ng-language-service/server/src/handlers/document_symbols.ts

+  // Get the navigation tree from TypeScript's language service.
+  // This includes classes, functions, variables, and for Angular files,
+  // also includes template symbols via the Angular language service.
+  const navigationTree = languageService.getNavigationTree(scriptInfo.fileName);


Should this only happen for TS files? What do we do about symbols for external templates (html files)

I've refactored the code to make the two paths clearer:

// For HTML template files, we only need Angular template symbols (no TS symbols) if (isHtmlFile) { // Returns template symbols at root level return convertTemplateSymbols(templateSymbols, scriptInfo); } // For TypeScript files, get navigation tree + merge template symbols into classes // ... TS symbols with (template) node nested under class

Test at ivy_spec.ts:411 verifies external HTML templates work.

I see in the screenshots that the document symbols are separated by the provider. In that case, should we even include the TS document symbols in TS files?

hmm, yes it is duplicating some positions, but so is html template one doing - should it also skip positions handled by native html? or make it configurable mayby?

For typescript, I think we should only include the parents of the inline template but should not provide other things from typescript (e.g. ngOnInit random various functions in the file, etc). For HTML, we can leave it as-is to keep it consistent for inline and external templates.

packages/language-service/src/document_symbols.ts

atscott · 2026-01-21T21:02:53Z

vscode-ng-language-service/client/src/client.ts

      args.push('--suppressAngularDiagnosticCodes', suppressAngularDiagnosticCodes);
    }

+    const documentSymbolsEnabled = config.get<boolean>('angular.documentSymbols.enabled', true);


We use middleware above to prevent the angular language server from processing files in projects that don't use Angular. Since the extension activates on all html and ts files, this is relatively important.

Thx for the hint! Added the provideDocumentSymbols middleware with isInAngularProject guard.

kbrilla · 2026-01-21T23:02:31Z

Screenshots demonstrating Document Symbols feature

TypeScript file with inline template (`NxWelcome` - no "Component" suffix)

Shows the component class with the (template) node containing Angular template symbols:

@if (title) control flow block with proper icon
Nested <span> and <div> elements
Class members (title property)

External HTML template (`app.html`)

Shows Angular symbols at root level for external templates:

@if (title) control flow block
<app-nx-welcome> component element
Both Angular Language Service and HTML Language Features sections working together

Key features visible in screenshots:

✅ Component without "Component" suffix works correctly
✅ Inline template symbols nested under class
✅ External template symbols at root level
✅ Control flow blocks (@if) with proper icons
✅ Breadcrumb navigation shows Angular hierarchy

kbrilla · 2026-01-21T23:21:02Z

Additional Features/Fixes Added During Testing

While testing and addressing review feedback, I found and fixed two additional edge cases:

1. Components Without "Component" Suffix

Issue: Classes like NxWelcome (without "Component" suffix) didn't get template symbols merged correctly.

Root cause: The original merge logic relied on class name ending with "Component" as a heuristic.

Fix: Added className property to TemplateDocumentSymbol API. Template symbols are now explicitly tagged with their owning class name, enabling reliable merging regardless of naming conventions.

2. Multiple Components Per File

Issue: Files with multiple components (common in tests, storybooks, demo files) didn't work - all template symbols went into the first class.

Fix: Server now groups template symbols by className and merges each group into the correct component class.

Tests added:

'provides document symbols for component without "Component" suffix'
'provides document symbols for multiple components in one file'

Both scenarios are now documented in the PR description under "Multi-Component Support".

This commit adds infrastructure for features to request configuration from the VS Code client using the LSP workspace/configuration protocol. This is the preferred approach over CLI arguments because: 1. Configuration changes take effect immediately without restarting 2. Supports per-workspace and per-folder configuration 3. VS Code automatically merges settings from different scopes: - Default settings - User settings (global) - Workspace settings - Workspace folder settings - Language-specific settings The new utilities include: - getWorkspaceConfiguration: Request multiple config sections at once - getConfigurationSection: Convenience wrapper for single sections - flattenConfiguration: Flatten nested config to dot-notation keys This infrastructure will be used by: - Inlay hints feature (PR angular#66731) - Document symbols feature (PR angular#66690)

kbrilla · 2026-01-24T09:08:57Z

🔗 Dependency Update

This PR now depends on #66734 (feat(language-server): add shared workspace/configuration utilities).

Changes in this update:

Removed CLI arguments: --disableDocumentSymbols and --showImplicitForVariables CLI args have been removed
Now uses workspace/configuration: Settings are fetched dynamically via LSP workspace/configuration request using the new shared utilities from feat(language-server): add shared workspace/configuration utilities #66734
Benefits: Users can now change document symbols settings without restarting the language server

Merge Order:

First merge feat(language-server): add shared workspace/configuration utilities #66734 (workspace/configuration infrastructure)
Then this PR can be merged

The PR has been rebased onto the feat/workspace-configuration branch.

kbrilla · 2026-01-25T23:01:11Z

Update: Hybrid Approach Implemented

Following @atscott's feedback, I've implemented the hybrid approach (Option 1 + 2 from the analysis):

Changes:

Default behavior (filtering): By default, only component classes with templates are shown in the outline - no TypeScript methods/properties
New configuration: Added angular.documentSymbols.showTypescriptSymbols setting to opt-in to full TypeScript symbols

Default behavior (new):

MyComponent (class)
└── (template)
    ├── @if (condition)
    └── <button>

With `showTypescriptSymbols: true`:

MyComponent (class)
├── ngOnInit (method)
├── onClick (method)
├── someProperty (property)
└── (template)
    ├── @if (condition)
    └── <button>

Testing:

Updated existing test to verify default filtering behavior
Added test for showTypescriptSymbols: true configuration
Added test for multiple components in a single file
Added test for TypeScript files without Angular templates

All 53 specs pass.

Documentation:

Updated README with new setting and visual examples
Updated package.json with setting description

atscott · 2026-01-25T23:55:48Z

New configuration: Added angular.documentSymbols.showTypescriptSymbols setting to opt-in to full TypeScript symbols

sorry, that’s not really what I asked. Please remove all typescript symbols outside of the ancestors of the template property

atscott · 2026-01-26T17:36:39Z

vscode-ng-language-service/server/src/config.ts

+ * );
+ * ```
+ */
+export async function getConfigurationSection<T = unknown>(


I don't see this used anywhere

kbrilla · 2026-02-24T20:49:14Z

I'm leaving out inlay styles support: styles: [`test{}`] as it requires more changes unrelated to document symbols, so I will post a separate PR with it not to bloat this PR #67266

…ettings grouping Add shared workspace configuration helper utilities and move extension settings to grouped configuration sections, without inlay-hint feature options yet.

@if

…lates Adds comprehensive Document Symbols support for Angular templates, enabling the Outline panel, breadcrumbs navigation, and 'Go to Symbol' (Cmd+Shift+O / Ctrl+Shift+O) features to work with Angular template syntax. Features: - Block syntax: @if, @else, @for, @switch, @case, @defer, @Placeholder, etc. - Structural directives: *ngIf, *ngFor, *ngSwitch, etc. - HTML elements and components - Template reference variables (#ref) - Loop variables and aliases (let item, let i = $index) - @let declarations For TypeScript files with inline templates, shows component class containers with template symbols nested inside (no TypeScript methods/properties shown). For external HTML templates, shows template symbols at root level. Configuration: - angular.documentSymbols.enabled: Enable/disable feature (default: true) - angular.documentSymbols.showImplicitForVariables: Show implicit @for variables Depends on workspace/configuration utilities from the previous commit. Closes angular#66691

pullapprove bot requested a review from devversion January 21, 2026 19:57

angular-robot bot added detected: feature PR contains a feature commit area: language-service Issues related to Angular's VS Code language service labels Jan 21, 2026

ngbot bot modified the milestone: Backlog Jan 21, 2026

JeanMeche requested a review from atscott January 21, 2026 20:40

atscott reviewed Jan 21, 2026

View reviewed changes

kbrilla force-pushed the feat/document-symbols-templates branch from 9b9c431 to 9e2edd7 Compare January 21, 2026 22:34

kbrilla force-pushed the feat/document-symbols-templates branch 2 times, most recently from 8b102aa to a0de8d6 Compare January 21, 2026 23:17

This was referenced Jan 23, 2026

feat(language-service): add Angular-specific Inlay Hints (LSP 3.17) #66731

Closed

feat(language-service): add Angular-specific Inlay Hints (LSP 3.17) #66730

Open

kbrilla mentioned this pull request Jan 24, 2026

feat(language-server): add shared workspace/configuration utilities #66734

Closed

kbrilla force-pushed the feat/document-symbols-templates branch from a0de8d6 to 4b96714 Compare January 24, 2026 09:08

kbrilla force-pushed the feat/document-symbols-templates branch from 4b96714 to 6fabcea Compare January 25, 2026 22:59

kbrilla mentioned this pull request Jan 25, 2026

feat(language-service): add Document Symbols support for Angular templates #66691

Open

kbrilla force-pushed the feat/document-symbols-templates branch from 6fabcea to e57626d Compare January 25, 2026 23:50

atscott reviewed Jan 26, 2026

View reviewed changes

kbrilla force-pushed the feat/document-symbols-templates branch from e57626d to c9b1442 Compare January 26, 2026 22:55

kbrilla force-pushed the feat/document-symbols-templates branch from c9b1442 to 5ca4d1d Compare February 23, 2026 22:35

angular-robot bot added the area: vscode-extension Issues related to the Angular Language Service VsCode extension label Feb 23, 2026

kbrilla force-pushed the feat/document-symbols-templates branch from 5ca4d1d to ac699af Compare February 24, 2026 12:56

refactor(vscode-extension): add workspace configuration helpers and s…

87d4552

…ettings grouping Add shared workspace configuration helper utilities and move extension settings to grouped configuration sections, without inlay-hint feature options yet.

kbrilla added 3 commits February 24, 2026 22:19

refactor(vscode-extension): harden workspace config lifecycle

fde85ef

test(language-service): cover document symbols microsyntax cases

8ac4109

kbrilla force-pushed the feat/document-symbols-templates branch from 975ac56 to 8ac4109 Compare February 24, 2026 21:20

Conversation

kbrilla commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR: feat(language-service): add Document Symbols support for Angular templates

Description

Features

Block Syntax Support

Structural Directive Support

Template File Support

Multi-Component Support

Variables and References

SymbolKind Mappings

Configuration

angular.documentSymbols.enabled (default: true)

angular.documentSymbols.showImplicitForVariables (default: false)

Example

Breaking Changes

Related Issues

AI Disclosure

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kbrilla commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Screenshots demonstrating Document Symbols feature

TypeScript file with inline template (NxWelcome - no "Component" suffix)

External HTML template (app.html)

Uh oh!

kbrilla commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional Features/Fixes Added During Testing

1. Components Without "Component" Suffix

2. Multiple Components Per File

Uh oh!

kbrilla commented Jan 24, 2026

🔗 Dependency Update

Changes in this update:

Merge Order:

Uh oh!

kbrilla commented Jan 25, 2026

Update: Hybrid Approach Implemented

Changes:

Default behavior (new):

With showTypescriptSymbols: true:

Testing:

Documentation:

Uh oh!

atscott commented Jan 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kbrilla commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kbrilla commented Jan 21, 2026 •

edited

Loading

`angular.documentSymbols.enabled` (default: `true`)

`angular.documentSymbols.showImplicitForVariables` (default: `false`)

kbrilla commented Jan 21, 2026 •

edited

Loading

TypeScript file with inline template (`NxWelcome` - no "Component" suffix)

External HTML template (`app.html`)

kbrilla commented Jan 21, 2026 •

edited

Loading

With `showTypescriptSymbols: true`:

kbrilla commented Feb 24, 2026 •

edited

Loading