Components

Icon

The <nys-icon> is a visual symbol used to concisely convey meaning, action, status, or feedback and can add to visual appearance. Icons are meant to enhance, not replace, textual information. NYS Design System includes a curated subset of the Google Material Symbols rounded icon set.

<nys-icon name="check_circle" size="5xl" color="var(--nys-color-success)"></nys-icon>

Can't use NYS Design System web components in your project? Try using the CSS Variables instead.

Managing your icon `library`

Note: Version 1.19.3 fixes a number of issues introduced in 1.19.0. If you registered an override for the "default" library as a workaround when upgrading to 1.19.x, you can safely remove that override after upgrading to 1.19.3.

When using the <nys-icon>, you can choose to load in icons from any library. By default, <nys-icon> can load icons from any registered library, served locally or via a CDN. Below are three examples: pointing the default library to a different local location, adding a Font Awesome library and Material Icon library, and using the library property.

Override the `"default"` library

<script src="nysds.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
  NYSDS.registerIconLibrary("default", {
    resolver: (name) =>
      `/assets/icons/${name}.svg`,
  });
});
</script>

Overriding the `"default"` library in React-like Frameworks

import { registerIconLibrary } from '@nysds/components';
// Font Awesome Library
registerIconLibrary('font-awesome', {
  resolver: name =>
    `https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/svgs/solid/${name}.svg`,
  mutator: (svg) => {
    svg.setAttribute("fill", "currentColor");
  },
});
// Material Library
registerIconLibrary('material', {
  resolver: name =>
    `https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/${name}/default/24px.svg`,
  mutator: (svg) => {
    svg.setAttribute("fill", "currentColor");
  },
});

Using the `library` prop

Once you've registered one or more additional libraries, use the library prop on <nys-icon> to tell the component which library to pull a given icon from. Icons with no library prop set will continue to use the "default" library.

/** Font-awesome **/
<NysIcon name="house" library="font-awesome"></NysIcon>
/** Material **/
<NysIcon name="home" library="material"></NysIcon>
/** Default (no "library" prop needed) **/
<NysIcon name="upload_file"></NysIcon>
<NysIcon name="schedule"></NysIcon>

Accessibility

The <nys-icon> component includes the following accessibility-focused features:

ARIA Hidden by Default: If no ariaLabel is provided, the icon is hidden from screen readers by setting aria-hidden="true".

Customizable ARIA Label: If an ariaLabel is provided, the component automatically adds an aria-label attribute, making the icon accessible to screen readers.

Additional accessibility test and build content is coming soon, in a new format.

Options

Size

You can scale icons either relatively (based on the parent element’s font size) or literally (with predefined size values). The icons support two sizing systems: relative sizes and literal sizes.

Relative Sizing

To scale an icon relative to the inherited font size, pass a size variant like size=[variant name] as a prop. The values will scale based on the current font size of the parent element.

xs (extra small): 75% of parent font size
sm (small): 87.5% of parent font size
md (medium): 100% of parent font size -- Default
lg (large): 112.5% of parent font size
xl (extra large): 125% of parent font size
2xl (double extra large): 150% of parent font size
3xl (triple extra large): 187.5% of parent font size
4xl (quadruple extra large): 225% of parent font size
5xl (quintuple extra large): 300% of parent font size

<nys-icon name="upload_file" size="xs"></nys-icon>
<nys-icon name="upload_file" size="xl"></nys-icon>
<nys-icon name="upload_file" size="5xl"></nys-icon>

Literal Sizing

For fixed, predefined sizes, you can use literal sizes. These sizes are defined in rem units, which provide fixed scaling options.

12: 0.75rem = 12px
14: 0.875rem = 14px
16: 1rem = 16px
18: 1.125rem = 18px
20: 1.25rem = 20px
24: 1.5rem = 24px
32: 2rem = 32px
40: 2.5rem = 40px
50: 3.125rem = 50px

<nys-icon name="upload_file" size="16"></nys-icon>
<nys-icon name="upload_file" size="32"></nys-icon>
<nys-icon name="upload_file" size="50"></nys-icon>

Color

You can override the color of an icon by setting a color prop. You can use CSS HEX values, CSS color names, or CSS variables

<nys-icon ariaLabel="Upload file icon" name="upload_file" color="#db117d" size="5xl"></nys-icon>

Rotate

You can rotate an icon by passing the angle as a number i.e: rotate="20" will rotate the icon by 20 degrees clockwise.

<nys-icon rotate="20" ariaLabel="Upload file icon" name="upload_file" size="5xl"></nys-icon>

Flip

Set an icon to flip horizontally, vertically, or in both directions by using the flip property. Available values are horizontal, vertical, and both. This example is both.

<nys-icon flip="both" ariaLabel="Upload file icon" name="social_linkedin" size="5xl"></nys-icon>

Load the Font Awesome library

You can load the Font Awesome library locally or by using their Content Delivery Network (CDN).

<script src="nysds.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
  // ── Font Awesome (loaded from CDN) ────────
  NYSDS.registerIconLibrary("font-awesome", {
    resolver: (name) =>
      `https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/svgs/solid/${name}.svg`,
    mutator: (svg) => {
      svg.setAttribute("fill", "currentColor");
    },
  });
});
</script>

Use the library prop to connect

/** Font-awesome **/
<NysIcon name="house" library="font-awesome"></NysIcon>
/** Default (no "library" prop needed) **/
<NysIcon name="upload_file"></NysIcon>

Font Awesome example (loaded via CDN)

house

user

star

heart

bell

magnifying-glass

circle-check

triangle-exclamation

Load the Material library

This demo assumes you have installed the material icon NPM package and want to reference it locally, rather than via CDN.

<script src="nysds.js"></script>
<script>
  // ── Material (loaded from local file system) ────────
  NYSDS.registerIconLibrary("material", {
    resolver: (name) =>
      `https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/${name}/default/24px.svg`,
    mutator: (svg) => {
      svg.setAttribute("fill", "currentColor");
    },
  });
</script>

Use the library prop to connect

/** Material **/
<NysIcon name="home" library="material"></NysIcon>
/** Default (no "library" prop needed) **/
<NysIcon name="upload_file"></NysIcon>

Material icon example (loaded locally)

home

person

star

favorite

notifications

check_circle

warning

Default icons

Here are the icons available in the "default" icon set.

Core

account_circle

add

attach_file

calendar_month

cancel

code

content_copy

check

delete

download

download_done

drive_folder_upload

edit_square

expand_all

filter_list

filter_alt

help

language

location_on

link

mail

more_vert

open_in_new

phone_in_talk

progress_activity

publish

remove

sort

schedule

sms

thumb_down

thumb_up

upload_file

visibility

visibility_off

notifications

social_bluesky

social_facebook

social_flickr

social_google_play

social_instagram

social_linkedin

social_pinterest

social_rss

social_snapchat

social_soundcloud

social_tiktok

social_threads

social_tumblr

social_vimeo

social_x

social_youtube

Arrows

arrow_back

arrow_downward

arrow_forward

arrow_upward

Chevrons

chevron_down

chevron_up

chevron_left

chevron_right

Environmental

ac_unit

air

clear_day

coronavirus

rainy

Intent

check_circle

emergency_home

error

info

warning

Filled

account_balance_filled

cancel_filled

language_filled

lock_filled

Usage

Do

Use icons to draw attention to actions, help users scan for key information, or enhance recognizable common actions (e.g., search, download, share).
Pair icons with a text label—few icons are universally understood alone.
Use icons consistently: same icon and label for the same meaning throughout your app.
Use ariaLabel when the icon conveys meaning, so screen readers can announce its purpose.
Use icons from the NYS Design System library; if unavailable, use Google Material Symbols (rounded, unfilled).
Match icon size and color to the design system.

Don't

Use an icon if its meaning isn't immediately clear—if you suspect users won't recognize it, remove it.
Use icons to compensate for unclear page hierarchy or confusing content organization.
Use standalone icons for actions—use <nys-button> with an icon inside instead.
Replace meaningful text with icons unless the icon is universally recognized or paired with a label.
Overuse icons—too many create visual noise and reduce focus.
Use excessive icon customization that breaks design consistency.

Properties

Property	Type	Default
`ariaLabel`	String	`""`
`color`	String (CSS HEX, CSS color name, or CSS variable)	`""`
`flip`	`"horizontal"`, `"vertical"`, `"both"`	`""`
`library`	String	`"default"`
`name`	String	`""`
`rotate`	integer	`0`
`size`	`"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, `"2xl"`, `"3xl"`, `"4xl"`, `"5xl"`, `"12"`, `"14"`, `"16"`, `"18"`, `"20"`, `"24"`, `"32"`, `"40"`, `"50"`	`"md"`

Style Overrides

These CSS custom properties are exposed for developers to customize the visual appearance of the component when necessary, beyond the defaults provided by the NYS Design System. Set them on the component selector to override the default styles.

nys-component {
  --nys-component-background-color: var(--nys-color-accent);
  --nys-component-color: var(--nys-color-ink);
}

CSS Variable	Description
`--nys-icon-size`	Width and height of the component
Can't find a property you need? Explore existing options, or propose a new one with a Component Proposal.

Events

This component does not emit any custom events.

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: July 11, 2026