In the Angular CDK, what does the `cdk-visually-hidden` class do, and why use it instead of `display: none`?
answer
- seen by nobody, heard by some
- removed from the accessibility tree
- a one-pixel clipped box
- a Sass mixin emits it
- no reveal on focus
basics
~20 scdk-visually-hidden shrinks an element to a clipped, absolutely positioned one-pixel box, so it vanishes visually but stays in the accessibility tree. display: none removes it for screen readers too, so hidden helper text would never be read.
solid answer
~40 sThe CDK's `.cdk-visually-hidden` class hides content from sight while keeping it available to assistive technology: it sets `position: absolute`, a 1px width and height, `clip: rect(0 0 0 0)`, `overflow: hidden`, a negative margin and `white-space: nowrap`. `display: none` or `visibility: hidden` would remove the element from the accessibility tree, so a screen reader would skip it. Typical uses are extra text such as 'Remove filter: Size M' on an icon-only chip, or a native checkbox under a custom visual. You emit the class with `@include cdk.a11y-visually-hidden();` from `@use '@angular/cdk';` in a global stylesheet; several CDK utilities and Material components load it on their own, but your markup should not rely on that.
code
scss · 4 lines@use '@angular/cdk';
// Emits the .cdk-visually-hidden class once for the whole app.
@include cdk.a11y-visually-hidden();go deeper
Know that cdk-visually-hidden hides content from sight but not from screen readers, while display: none hides it from both.
Explain the clipping technique behind the class and how to emit it with the a11y-visually-hidden Sass mixin in a global stylesheet.
Point out the hidden dependency when the class is loaded only by other CDK pieces, and the missing focus-reveal rule for focusable elements.
Decide where a shared visually-hidden utility lives in an app or kit so every team uses the same class instead of local copies.
## Two audiences, one element Some content is only useful to people using **assistive technology**, such as screen readers. An icon-only button that removes a filter chip shows a small cross to sighted users, but a screen-reader user needs to hear what it removes. A custom-styled checkbox may draw its own box while the real `<input type="checkbox">` underneath must still be reachable and announced. The common CSS ways of hiding things do not serve that case: - `display: none` removes the element from layout **and** from the accessibility tree. - `visibility: hidden` also hides it from assistive technology. - Zero `width` or `height` can cause some assistive technology to skip the element. The Angular CDK's answer is the **`cdk-visually-hidden`** class from its accessibility styles. ## What the class sets The class is emitted by the `a11y-visually-hidden` Sass mixin in `@angular/cdk`. Its rules are: | Property | Value | Purpose | |---|---|---| | `position` | `absolute` | takes the element out of the layout flow | | `width` / `height` | `1px` | keeps a real, non-zero box | | `margin` | `-1px` | stops the box from nudging neighbours | | `clip` | `rect(0 0 0 0)` | clips the visible area to nothing | | `overflow` | `hidden` | hides anything beyond the box | | `white-space` | `nowrap` | avoids a browser bug with long wrapped text | | `left` | `0` (`right: 0` under `[dir='rtl']`) | prevents scroll side effects | It also resets `border`, `padding`, `outline` and the native `appearance`, so a native control given the class does not render a stray widget. ## How to get the class into your app 1. In a global stylesheet, `@use '@angular/cdk';`. 2. `@include cdk.a11y-visually-hidden();` once, at the top level. 3. Add `class="cdk-visually-hidden"` to the elements that should be heard but not seen. The CDK's a11y partial still defines an older `a11y()` mixin marked deprecated, but the `@angular/cdk` entry point forwards only `a11y-visually-hidden`, so that is the name to use. You may find the class already working without step 2. The CDK's focus trap (whose anchors use it), the `cdkAriaLive` directive, `AriaDescriber` and several Material components such as options, chips and the datepicker load the style on demand. The CDK's guide says Material's theming includes it, but in the v22 source Material's core styles do not emit the class; individual components load it on demand. Relying on that is fragile: a page that uses none of those pieces would show your hidden text in plain view. Including the mixin yourself makes the dependency explicit. ## Examples in a filter UI - An icon-only remove button on a chip: `<span class="cdk-visually-hidden">Remove filter: Size M</span>` beside the icon. - A results header that visually shows only a number but should read as a sentence. - The CDK's own `LiveAnnouncer`, which creates its shared live region with this class so announcements are spoken but never displayed. ## The edge case: focusable elements The class has **no** rule that reveals the element when it receives focus. If you put it on a link or button that keyboard users can reach, they will tab to something invisible. For a skip link or similar control that should appear on focus, you need an additional style of your own that undoes the clipping on `:focus`. ## Summary - `cdk-visually-hidden` hides visually and keeps the element in the accessibility tree. - `display: none` and `visibility: hidden` hide it from everyone. - Emit the class yourself with `cdk.a11y-visually-hidden()` rather than counting on another component to load it.
- Why is it risky to rely on Angular Material to provide the cdk-visually-hidden class?In the source, the style is loaded on demand by specific pieces: the focus trap, `cdkAriaLive`, `AriaDescriber` and some Material components such as options and chips. A page that renders none of them may not have the class, and your hidden text appears on screen. Including `cdk.a11y-visually-hidden()` once in global styles removes the dependency.
- What goes wrong if you put cdk-visually-hidden on a link that keyboard users can reach?The class has no focus-reveal rule, so the link stays a clipped one-pixel box while focused. Keyboard users reach an element they cannot see. A skip link needs an extra style that removes the clipping on `:focus`.
- cdk-visually-hidden is the same as display: none.
- display: none text is still read by screen readers.
- The class makes a focused element reappear automatically.
- Material always includes the class, so the mixin is never needed.
- aria-hidden on the text is how you keep it for screen readers.