- Published on
Resolving Missing `Description` or `aria-describedby` Warning in ShadCN UI
- Authors
- Name
- Ripal & Zalak
Introduction
When working with ShadCN UI components like Sheet
or Dialog
, you may encounter a warning in the console:
Warning: Missing `Description` or `aria-describedby={undefined}` for {DialogContent}.
This issue occurs because ShadCN UI builds on Radix UI primitives, which enforce accessibility best practices, including the need for descriptive content in dialog components. This guide explains why this happens and how to resolve it.
Understanding the Warning
The warning occurs because ShadCN UI’s Sheet
component is an extension of the Dialog
component. According to Radix UI's accessibility guidelines, each DialogContent
(or SheetContent
) must have a Description
or an aria-describedby
attribute to provide context for screen readers.
Solutions to Resolve the Warning
SheetDescription
1. Add a The simplest way to fix the warning is by including a SheetDescription
within the SheetContent
. For example:
<Sheet open={openMenu} onOpenChange={setOpenMenu}>
<SheetTrigger asChild>
<Button variant="ghost">
<MenuIcon size="2em" />
</Button>
</SheetTrigger>
<SheetContent side="right">
<SheetHeader>
<SheetDescription>Description of the sheet content.</SheetDescription>
</SheetHeader>
<div>
<p>Sheet Content</p>
</div>
</SheetContent>
</Sheet>
This ensures compliance with accessibility requirements.
2. Use a Visually Hidden Description
If you don’t want the description to appear visually, you can hide it while still satisfying accessibility guidelines. Use Radix UI’s VisuallyHidden
component:
import { VisuallyHidden } from '@radix-ui/react-visually-hidden'
;<Sheet open={openMenu} onOpenChange={setOpenMenu}>
<SheetTrigger asChild>
<Button variant="ghost">
<MenuIcon size="2em" />
</Button>
</SheetTrigger>
<SheetContent side="right">
<SheetHeader>
<VisuallyHidden>
<SheetDescription>Hidden description for accessibility.</SheetDescription>
</VisuallyHidden>
</SheetHeader>
<div>
<p>Sheet Content</p>
</div>
</SheetContent>
</Sheet>
aria-describedby={undefined}
3. Add If you prefer not to include a description, you can suppress the warning by explicitly setting aria-describedby
to undefined
in the SheetContent
:
<Sheet open={openMenu} onOpenChange={setOpenMenu}>
<SheetTrigger asChild>
<Button variant="ghost">
<MenuIcon size="2em" />
</Button>
</SheetTrigger>
<SheetContent side="right" aria-describedby={undefined}>
<div>
<p>Sheet Content</p>
</div>
</SheetContent>
</Sheet>
While this removes the warning, it's not recommended as it bypasses accessibility guidelines.
4. Include a Static Description
For static components where descriptions don’t change, you can add a description directly in the SheetHeader
:
<SheetHeader>
<SheetDescription>Description goes here.</SheetDescription>
</SheetHeader>
This approach is ideal for dialogs or sheets with consistent content.
Best Practices
- Always provide meaningful descriptions for dialog content to ensure accessibility.
- Use visually hidden descriptions when descriptions aren’t necessary for sighted users.
- Avoid bypassing accessibility requirements unless absolutely necessary.
Conclusion
By including a SheetDescription
, using VisuallyHidden
, or explicitly managing aria-describedby
, you can resolve the "Missing Description or aria-describedby" warning in ShadCN UI. These practices not only improve accessibility but also ensure your application adheres to UI best practices.
Let us know your thoughts or share your challenges in the comments below!