# VisuallyHidden
## Summary
`VisuallyHidden` keeps content available to assistive technology while removing it from visual layout. It supports a native wrapper or `asChild` composition through `Slot`.
## Imports
```tsx
import { VisuallyHidden, type VisuallyHiddenProps } from '@vega-ui/react';
```
## Exported Types
- `VisuallyHiddenProps`
## Basic Usage
```tsx
import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react';
const plans = [
{ name: 'Starter', price: '$0', slug: 'starter' },
{ name: 'Team', price: '$12', slug: 'team' },
{ name: 'Enterprise', price: 'Custom', slug: 'enterprise' },
];
export default function BasicUsage() {
return (
{plans.map((plan) => (
{plan.name}{plan.price}
Learn more
about the {plan.name} plan
))}
);
}
```
## Variants
- Rendering: default wrapper or `asChild`
- Usage: hidden label, description, or status text
## Edge Cases
- Hidden text should stay synchronized with the visible UI state.
- `VisuallyHidden` is not a substitute for visible labels by default.
- `asChild` keeps the hidden styling but changes the underlying element.
## Common Mistakes
- Leaving hidden text stale when the visible state changes.
- Using hidden text to paper over poor visible labeling.
- Hiding content that should actually be visible for most users.
## Examples
### Basic
#### Basic: unique names for repeated links
Three "Learn more" links sound identical in a links list. Hidden text completes each name ("Learn more about the Team plan") without changing the layout.
```tsx
import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react';
const plans = [
{ name: 'Starter', price: '$0', slug: 'starter' },
{ name: 'Team', price: '$12', slug: 'team' },
{ name: 'Enterprise', price: 'Custom', slug: 'enterprise' },
];
export default function BasicUsage() {
return (
{plans.map((plan) => (
{plan.name}{plan.price}
Learn more
about the {plan.name} plan
))}
);
}
```
#### Basic: icon-only button with a text name
Hidden text inside the button becomes its accessible name and can include data the visual badge shows only as a number. The badge itself is `aria-hidden` so the count is not read twice. `asChild` renders a ``, because the default `
` is not valid inside a button.
```tsx
import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react';
import { BellIcon } from '@vega-ui/icons';
import { useState } from 'react';
export default function IconOnlyControlLabel() {
const [unread, setUnread] = useState(4);
return (
setUnread(0)} style={{ position: 'relative' }}>
Notifications, {unread} unread
{unread > 0 && (
{unread}
)}
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: live announcement for a visual counter
The cart counter changes silently for screen readers. A hidden `role='status'` region receives a full sentence on every change, and the visual counter stays `aria-hidden`.
```tsx
import { Button, Icon, VisuallyHidden } from '@vega-ui/react';
import { ShoppingCartIcon } from '@vega-ui/icons';
import { useState } from 'react';
const products = ['Linen shirt', 'Canvas tote', 'Wool socks'];
export default function HiddenStatusText() {
const [cart, setCart] = useState([]);
const [announcement, setAnnouncement] = useState('');
const add = (product: string) => {
const next = [...cart, product];
setCart(next);
setAnnouncement(`${product} added. Cart has ${next.length} items.`);
};
return (
{products.map((product) => (
))}
{cart.length}
{announcement}
);
}
```
### Form/Integration
#### Form/Integration: hidden description for a visual adornment
The `$` prefix is visual only. A hidden description linked with `aria-describedby` tells screen reader users the currency; the value is read with `FormData` on submit. `VisuallyHidden` does not accept `id`, so the id goes on the `asChild` span.
```tsx
import { Button, Label, TextField, TextFieldInput, VisuallyHidden } from '@vega-ui/react';
import { FormEvent, useState } from 'react';
export default function HiddenHelperDescription() {
const [budget, setBudget] = useState('');
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
setBudget(String(new FormData(event.currentTarget).get('budget')));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: hidden dialog title
A lightbox has no visible heading, but the dialog still needs a name. A hidden `
` is referenced with `aria-labelledby`, so the dialog is announced as "Floor plan, apartment 4B".
```tsx
import type { CSSProperties } from 'react';
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Icon,
IconButton,
VisuallyHidden,
} from '@vega-ui/react';
import { ImageIcon, XIcon } from '@vega-ui/icons';
export default function HiddenDialogCue() {
return (
);
}
```
### Error
#### Error: spoken prefix for an error message
The error is shown with color and an icon. A hidden "Error:" prefix gives the same signal to screen reader users when they reach the message through `aria-describedby`.
```tsx
import { Button, HelperText, Icon, Label, TextField, TextFieldInput, VisuallyHidden } from '@vega-ui/react';
import { CircleAlertIcon } from '@vega-ui/icons';
import { FormEvent, useState } from 'react';
export default function HiddenValidationCue() {
const [error, setError] = useState('');
const [saved, setSaved] = useState('');
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const domain = String(new FormData(event.currentTarget).get('domain'));
if (!domain.includes('.')) {
setError('Add a top-level domain, for example acme.com');
setSaved('');
return;
}
setError('');
setSaved(domain);
};
return (
);
}
```
### Disabled
#### Disabled: why an option is unavailable
Sold-out sizes are disabled and struck through. The strike-through is visual only, so hidden text adds ", sold out" to the button name, which screen readers still read in browse mode.
```tsx
import { Button, VisuallyHidden } from '@vega-ui/react';
import { useState } from 'react';
const sizes = [
{ label: 'S', inStock: true },
{ label: 'M', inStock: true },
{ label: 'L', inStock: false },
{ label: 'XL', inStock: false },
];
export default function HiddenDisabledExplanation() {
const [selected, setSelected] = useState('M');
return (
{sizes.map((size) => (
))}
Selected size: {selected}
);
}
```
### Edge
#### Edge: text alternative for a symbol rating
Star characters are read as "black star" one by one. They are hidden with `aria-hidden`, and a hidden span inside the paragraph reads "Rated 3 out of 5". `asChild` keeps a `` inside the `
`, where a `
` is not allowed.
```tsx
import { Text, VisuallyHidden } from '@vega-ui/react';
const reviews = [
{ author: 'Maria K.', rating: 5, text: 'Arrived in two days, fits perfectly.' },
{ author: 'Tom B.', rating: 3, text: 'Good fabric, but the sleeves run long.' },
];
export default function SlottedHiddenElement() {
return (
{reviews.map((review) => (
{review.author}
{'★'.repeat(review.rating)}{'☆'.repeat(5 - review.rating)}
Rated {review.rating} out of 5
{review.text}
))}
);
}
```
#### Edge: empty-looking table header
An actions column often has no visible header, yet an empty `
` leaves the cells without context. A hidden "Actions" header fixes that while the column stays visually empty.
```tsx
import { Icon, IconButton, VisuallyHidden } from '@vega-ui/react';
import { PencilIcon } from '@vega-ui/icons';
import { useState } from 'react';
const members = [
{ name: 'Jane Cooper', role: 'Owner' },
{ name: 'Wade Warren', role: 'Editor' },
{ name: 'Esther Howard', role: 'Viewer' },
];
export default function HiddenTableHeader() {
const [editing, setEditing] = useState('');
return (
Name
Role
Actions
{members.map((member) => (
{member.name}
{member.role}
setEditing(member.name)}
>
))}
{editing === '' ? '' : `Editing ${editing}`}
);
}
```
## Anatomy
### Overview
`VisuallyHidden` is a single-part primitive that applies the standard visually-hidden CSS pattern to its content.
### Required Parts
#### `VisuallyHidden`
Required. Owns the hidden-but-accessible rendering behavior.
### Optional Parts
There are no exported child parts.
### Composition Order
1. `VisuallyHidden`
2. hidden content
### Valid Composition Patterns
```tsx
import { Heading, Link, Text, VisuallyHidden } from '@vega-ui/react';
const plans = [
{ name: 'Starter', price: '$0', slug: 'starter' },
{ name: 'Team', price: '$12', slug: 'team' },
{ name: 'Enterprise', price: 'Custom', slug: 'enterprise' },
];
export default function BasicUsage() {
return (
{plans.map((plan) => (
{plan.name}{plan.price}
Learn more
about the {plan.name} plan
))}
);
}
```
### Invalid Composition Patterns
#### Hidden text used instead of visible label by default
The UI becomes harder to use for sighted users.
#### Hidden content left unsynchronized with the visible state
Assistive technology users receive stale information.