angular/components

docs: clarify support for ViewEncapsulation.ShadowDom

Open

#13837 opened on Oct 26, 2018

View on GitHub
 (15 comments) (29 reactions) (0 assignees)TypeScript (24,044 stars) (6,650 forks)batch import
P2area: manydocselementshelp wanted

Description

Proposal

What is the expected behavior?

If ViewEncapsulation.ShadowDom is not supported, this should be called out in the docs to save developers time and frustration.

What is the current behavior?

ViewEncapsulation.ShadowDom is not supported and is not documented.

What are the steps to reproduce?

  1. Open https://stackblitz.com/edit/angular-i5jw3k?file=app/table-selection-example.ts
  2. Notice how the checkboxes aren't themed
  3. Open https://stackblitz.com/edit/angular-sbrzfb?file=app/input-overview-example.ts
  4. Notice how the inputs are not themed or styled properly

What is the use-case or motivation for changing an existing behavior?

To save developers time and frustration.

Which versions of Angular, Material, OS, TypeScript, browsers are affected?

Angular: 7.0.0 Angular Material: 7.0.2 TypeScript: ~3.1.1 Browsers: Tested on Chrome, Firefox, and Safari latest stable versions

Is there anything else we should know?

Nope

Contributor guide

Tech stack
typescripthtmlcss
Domain
documentationfrontend
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
basic Angular knowledgefamiliarity with ViewEncapsulation
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
First, locate the documentation for Angular Material components, likely in the `guides` or `cdk` directory of the repository (e.g., `guides/theming.md` or `cdk/a11y/README.md`). Look for any existing sections on styling or view encapsulation. Then, add a clear note that `ViewEncapsulation.ShadowDom` is not supported for Material components, explaining the impact (e.g., checkboxes and inputs losing themes) and recommend using `ViewEncapsulation.Emulated` or `None` instead. Reference the StackBlitz examples provided in the issue to illustrate the problem. Finally, update the component API docs where relevant to mention this limitation.