# Icon (/components/visuals/icon)



`Icon` renders a symbol from the generated Luke UI spritesheet. It needs an
`IconSpritesheetProvider` ancestor so it can resolve the spritesheet URL.

To find an icon, set its size or colour, or set up the spritesheet, see
[Iconography](/docs/iconography).

apps/docs/src/examples/icon/basic.tsx

```tsx
import { Icon } from '@luke-ui/react/icon';

export default () => {
	return <Icon name="search" />;
};
```

## Create a custom icon [#create-a-custom-icon]

Use `createIcon` for a one-off icon that is not in the generated spritesheet. It returns a component
with the same sizing and accessibility behaviour as `Icon`.

apps/docs/src/examples/icon/custom.tsx

```tsx
import { createIcon } from '@luke-ui/react/icon';

const HeartIcon = createIcon({
	path: (
		<path d="M12 21a1 1 0 0 1-.7-.3L5 14.5a5 5 0 1 1 7-6 5 5 0 1 1 7 6l-6.3 6.2a1 1 0 0 1-.7.3Z" />
	),
});

export default () => {
	return <HeartIcon size="small" title="Add to favourites" />;
};
```

## Accessibility [#accessibility]

Pass `title` when an icon conveys meaning without adjacent text, such as a standalone status icon.
`Icon` then exposes it to assistive technology with `role="img"`. When `title` is omitted, the icon
is decorative.

Read [Iconography](/docs/iconography#accessibility) for decorative and informative examples.

## Related components [#related-components]

Use [Emoji](/components/typography/emoji) when the visual content is an emoji that needs an
accessible label.

## API [#api]

### IconProps [#iconprops]

<ComponentPropsTable
  id="type-table-icon.tsx-IconProps"
  type="{
  &#x22;id&#x22;: &#x22;icon.tsx-IconProps&#x22;,
  &#x22;name&#x22;: &#x22;IconProps&#x22;,
  &#x22;description&#x22;: &#x22;Props for the built-in `Icon` component.&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;name&#x22;,
      &#x22;description&#x22;: &#x22;Icon name from the generated icon set.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;\&#x22;search\&#x22; | \&#x22;copy\&#x22; | \&#x22;add\&#x22; | \&#x22;arrowDown\&#x22; | \&#x22;arrowLeft\&#x22; | \&#x22;arrowRight\&#x22; | \&#x22;arrowUp\&#x22; | \&#x22;bookOpen\&#x22; | \&#x22;check\&#x22; | \&#x22;checkCircle\&#x22; | \&#x22;chevronDown\&#x22; | \&#x22;chevronLeft\&#x22; | \&#x22;chevronRight\&#x22; | \&#x22;chevronUp\&#x22; | \&#x22;circleHalf\&#x22; | \&#x22;close\&#x22; | \&#x22;closeCircle\&#x22; | \&#x22;codeBlock\&#x22; | \&#x22;delete\&#x22; | \&#x22;edit\&#x22; | \&#x22;exclamationTriangle\&#x22; | \&#x22;expand\&#x22; | \&#x22;externalLink\&#x22; | \&#x22;minimize\&#x22; | \&#x22;mobilePhone\&#x22; | \&#x22;monitor\&#x22; | \&#x22;moon\&#x22; | \&#x22;sun\&#x22;&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;title&#x22;,
      &#x22;description&#x22;: &#x22;Accessible label. When set, the icon is announced as an image.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;className&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;id&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;style&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;React.CSSProperties | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-hidden&#x22;,
      &#x22;description&#x22;: &#x22;Indicates whether the element is exposed to an accessibility API.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;see&#x22;,
          &#x22;text&#x22;: &#x22;aria-disabled.&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;Booleanish | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;viewBox&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;size&#x22;,
      &#x22;description&#x22;: &#x22;Sets the icon size.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;'medium'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;\&#x22;large\&#x22; | \&#x22;medium\&#x22; | \&#x22;small\&#x22; | \&#x22;xsmall\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### CreateIconOptions [#createiconoptions]

<ComponentPropsTable
  id="type-table-icon.tsx-CreateIconOptions"
  type="{
  &#x22;id&#x22;: &#x22;icon.tsx-CreateIconOptions&#x22;,
  &#x22;name&#x22;: &#x22;CreateIconOptions&#x22;,
  &#x22;description&#x22;: &#x22;Options for `createIcon`.&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;path&#x22;,
      &#x22;description&#x22;: &#x22;SVG path content or a render function that returns path content.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ReactNode | ((props: TProps) => ReactNode)&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;viewBox&#x22;,
      &#x22;description&#x22;: &#x22;Static or dynamic viewBox value.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | ((props: TProps) => string | undefined) | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### CustomIconProps [#customiconprops]

<ComponentPropsTable
  id="type-table-icon.tsx-CustomIconProps"
  type="{
  &#x22;id&#x22;: &#x22;icon.tsx-CustomIconProps&#x22;,
  &#x22;name&#x22;: &#x22;CustomIconProps&#x22;,
  &#x22;description&#x22;: &#x22;Props used by `createIcon` for custom icon components.&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;className&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;id&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;style&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;React.CSSProperties | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;title&#x22;,
      &#x22;description&#x22;: &#x22;Accessible label. When set, the icon is announced as an image.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;aria-hidden&#x22;,
      &#x22;description&#x22;: &#x22;Indicates whether the element is exposed to an accessibility API.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;see&#x22;,
          &#x22;text&#x22;: &#x22;aria-disabled.&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;Booleanish | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;size&#x22;,
      &#x22;description&#x22;: &#x22;Sets the icon size.&#x22;,
      &#x22;tags&#x22;: [
        {
          &#x22;name&#x22;: &#x22;default&#x22;,
          &#x22;text&#x22;: &#x22;'medium'&#x22;
        }
      ],
      &#x22;type&#x22;: &#x22;\&#x22;large\&#x22; | \&#x22;medium\&#x22; | \&#x22;small\&#x22; | \&#x22;xsmall\&#x22; | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;union&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;viewBox&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string | undefined&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: false,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>

### IconSpritesheetProviderProps [#iconspritesheetproviderprops]

<ComponentPropsTable
  id="type-table-icon.tsx-IconSpritesheetProviderProps"
  type="{
  &#x22;id&#x22;: &#x22;icon.tsx-IconSpritesheetProviderProps&#x22;,
  &#x22;name&#x22;: &#x22;IconSpritesheetProviderProps&#x22;,
  &#x22;description&#x22;: &#x22;Props for `IconSpritesheetProvider`.&#x22;,
  &#x22;entries&#x22;: [
    {
      &#x22;name&#x22;: &#x22;children&#x22;,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;ReactNode&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;ReactNode&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    },
    {
      &#x22;name&#x22;: &#x22;href&#x22;,
      &#x22;description&#x22;: &#x22;URL to the generated sprite sheet file.&#x22;,
      &#x22;tags&#x22;: [],
      &#x22;type&#x22;: &#x22;string&#x22;,
      &#x22;simplifiedType&#x22;: &#x22;string&#x22;,
      &#x22;required&#x22;: true,
      &#x22;deprecated&#x22;: false
    }
  ]
}"
/>
