# Icon ## Summary `Icon` is the shared SVG wrapper for VegaUI icons and custom SVG content. It normalizes size through tokens and renders through `Slot`, which lets the child SVG receive the merged props directly. ## Imports ```tsx import { Icon, type IconProps, type IconSize } from '@vega-ui/react'; ``` ## Exported Types - `IconProps` - `IconSize` ## Basic Usage ```tsx import { Icon } from '@vega-ui/react'; import { CalendarIcon, MessageSquareIcon, PaperclipIcon } from '@vega-ui/icons'; export default function BasicUsage() { return ( ); } ``` ## Variants - Size: `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl` - Rendering: token size or explicit `width` / `height` - Content: VegaUI icon, custom SVG, or third-party SVG component ## Edge Cases - Explicit `width` or `height` bypasses the token size data attribute. - `Icon` sets `aria-hidden='true'` by default, which is correct for decorative usage but not for standalone semantic graphics. - `stroke='currentColor'` means icon color comes from surrounding text or control color. ## Common Mistakes - Using icon color alone to express state. - Letting icon size drift away from the surrounding control density. - Assuming every icon should be announced to assistive technology. ## Examples ### Basic #### Basic: icons beside text `Icon` adds `aria-hidden='true'` and `stroke='currentColor'` to its child SVG, so a glyph next to text is decorative and takes the text color of its parent. ```tsx import { Icon, Text } from '@vega-ui/react'; import { CircleCheckIcon, ShieldIcon, TriangleAlertIcon } from '@vega-ui/icons'; export default function InfoRow() { return ( ); } ``` #### Basic: size scale `size` maps to fixed pixel sizes from `4xs` (8px) to `xl` (28px). Pick the size that matches the text or control next to the icon. ```tsx import { Icon, type IconSize } from '@vega-ui/react'; import { StarIcon } from '@vega-ui/icons'; const sizes: IconSize[] = ['4xs', '3xs', '2xs', 'xs', 'sm', 'md', 'lg', 'xl']; export default function Sizes() { return (
{sizes.map((size) => (
{size}
))}
); } ``` ### Controlled/Stateful #### Controlled/Stateful: disclosure chevron The chevron rotates with CSS when the section opens; the state itself is exposed by `aria-expanded` on the button, never by the icon. ```tsx import { Button, Icon, Text } from '@vega-ui/react'; import { ChevronDownIcon } from '@vega-ui/icons'; import { useState } from 'react'; import './examples.css'; export default function DisclosureChevron() { const [expanded, setExpanded] = useState(false); return (
); } ``` ### Form/Integration #### Form/Integration: leading icon inside a text field `TextField` is a flex container, so an `Icon` placed before `TextFieldInput` becomes an adornment. The field keeps its visible `Label`; the icon only decorates. ```tsx import { Icon, Label, TextField, TextFieldInput } from '@vega-ui/react'; import { AtSignIcon } from '@vega-ui/icons'; import { FormEvent, useState } from 'react'; export default function InputAdornment() { const [handle, setHandle] = useState(''); const handleSubmit = (event: FormEvent) => { event.preventDefault(); setHandle(String(new FormData(event.currentTarget).get('handle'))); }; return (
{handle === '' ? 'Press Enter to save' : `Profile URL: example.com/@${handle}`}
); } ``` ### Layout/Overlay #### Layout/Overlay: icons inside buttons Leading and trailing icons sit in the button's flex gap. Inside `Button` the icon does not scale automatically, so set `size` to match the button size. ```tsx import { Button, Icon } from '@vega-ui/react'; import { ChevronDownIcon, DownloadIcon, PlusIcon } from '@vega-ui/icons'; export default function IconInsideAButton() { return (
); } ``` ### Error #### Error: icon in a validation message The field validates on blur. The error text, not the icon, carries the meaning; the icon inherits the error color from `HelperText` and the message is linked with `aria-describedby`. ```tsx import { HelperText, Icon, Label, TextField, TextFieldInput } from '@vega-ui/react'; import { CircleAlertIcon } from '@vega-ui/icons'; import { useState } from 'react'; export default function ErrorMessageIcon() { const [error, setError] = useState(''); const validate = (input: HTMLInputElement) => { if (input.validity.valid) { setError(''); return; } setError('Enter an email like name@company.com'); }; return (
validate(event.currentTarget)} /> {error !== '' && ( {error} )}
); } ``` ### Disabled #### Disabled: icons in disabled controls Because the glyph uses `currentColor`, it takes the disabled text color of its button without extra styles. The same works for muted helper copy. ```tsx import { Button, Icon, IconButton } from '@vega-ui/react'; import { LockIcon, Trash2Icon, UploadIcon } from '@vega-ui/icons'; export default function MutedControlIcon() { return (

Branding is managed by your organization admin

); } ``` ### Edge #### Edge: icon as the only status signal In a status column there is no visible text, and the icon stays `aria-hidden`. A `VisuallyHidden` span gives screen readers the status in words. ```tsx import { Icon, VisuallyHidden } from '@vega-ui/react'; import { CircleCheckIcon, CircleXIcon } from '@vega-ui/icons'; const checks = [ { name: 'Unit tests', passed: true }, { name: 'Lint', passed: true }, { name: 'Visual regression', passed: false }, ]; export default function StandaloneMeaningfulIcon() { return ( {checks.map((check) => ( ))}
Check Status
{check.name} {check.passed ? : } {check.passed ? 'Passed' : 'Failed'}
); } ``` #### Edge: directional icons in right-to-left layouts Arrows point in the reading direction, so in `dir='rtl'` they must be mirrored. Flip only directional glyphs; icons like a check or a clock stay as they are. ```tsx import { Button, Icon } from '@vega-ui/react'; import { ArrowRightIcon } from '@vega-ui/icons'; export default function RtlDirectionalIcon() { return (
); } ``` #### Edge: size outside the scale For an illustration-sized icon, set `--icon-size` directly. The `width` and `height` props are not forwarded to the SVG at the moment, so do not rely on them. ```tsx import type { CSSProperties } from 'react'; import { Heading, Icon, Text } from '@vega-ui/react'; import { InboxIcon } from '@vega-ui/icons'; export default function CustomIconSize() { return (
Inbox zero New requests from your team show up here.
); } ``` ## Anatomy ### Overview `Icon` is a single-part primitive that passes sizing and SVG props into its child through `Slot`. ### Required Parts #### `Icon` Required. Owns the shared size token contract and SVG prop forwarding. ### Optional Parts There are no exported child parts. ### Composition Order 1. `Icon` 2. one SVG child ### Valid Composition Patterns ```tsx import { Icon } from '@vega-ui/react'; import { CalendarIcon, MessageSquareIcon, PaperclipIcon } from '@vega-ui/icons'; export default function BasicUsage() { return ( ); } ``` ### Invalid Composition Patterns #### Non-SVG child content The wrapper is meant to forward SVG-like props and sizing. #### Standalone meaningful icon with no accompanying label or context The default `aria-hidden` behavior may make the meaning inaccessible.