Icons

Icons are provided through [Octicons](/octicons) and are represented using `<svg>` elements in HTML. They are most often used as decorative content but may also provide meaningful content in specific situations.

Usage

See the Octicons page for the full icon library and associated documentation.

The Code tab of the Octicons page shows how to render Octicons in React and Rails.

Markup

Decorative by default

By default, an icon represented as an <svg> element is considered decorative[^decorative]. Implementations must set aria-hidden="true" and focusable="false" directly on the <svg> element.

<svg aria-hidden="true" focusable="false">
  <!-- ... -->
</svg>

Checklist for decorative SVGs

The <svg> element must set aria-hidden="true"
The <svg> element must set focusable="false"

Contentful

In specific situations, an icon may not be considered decorative[^decorative] and is conveying information similar to an image or graphic.

Warning If you are attempting to label an interactive element with an icon using this method, please follow the directions in Within an interactive element instead.

<svg role="img" focusable="false">
  <title>A short, concise description</title>
  <path d="..." />
</svg>

Checklist for contentful SVGs

The <svg> element must set role="img"
The <svg> element must set focusable="false"
A <title> element must be included within the <svg> element

The focusable attribute is defined by SVG Tiny 1.2 and is only implemented in Internet Explorer and earlier versions of Microsoft Edge.

Within an interactive element, contentful by default

When an icon is used as the only descendant of an interactive element, the accessible name for the SVG is optimally provided by a nested title element. Provided this way, the text is on the page itself, and all text navigation functions are available to users of assistive technology, as opposed to being provided by ARIA attributes.

<button type="button">
  <svg focusable="false">
    <title>Add</title>
    <!-- ... -->
  </svg>
</button>

Checklist for contentful SVGs within an interactive element

The <svg> element must set focusable="false"
The <title> element must be provided

The focusable attribute is defined by SVG Tiny 1.2 and is only implemented in Internet Explorer and earlier versions of Microsoft Edge.

Props

An icon component may accept any valid <svg> attribute
An icon component must accept a size prop
An icon component must accept a prop in order to convey information through a <title> element, ideally name or label
An icon component may accept a children prop to allow callers to provide additional elements within the <svg> itself
An icon component must not accept a tabIndex prop

Name	Type	Default	Description
`fill`	`string`	`currentColor`	Set the color of the icon
`size`	`'small' \| 'medium' \| 'large'`		Render the octicon at a standard size
`name` or `label`	`string`		Provide an accessible label for the icon
`verticalAlign`	`'middle' \| 'text-bottom' \| 'text-top' \| 'top'`		Change the alignment of the icon