Icon

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

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

Can’t use NYSDS web components in your project? Try using the CSS Variables instead.


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.

  • 2xs (extra-extra small): 75% of parent font size
  • xs (extra small): 87.5% of parent font size
  • sm (small): 100% of parent font size -- Default
  • md (medium): 112.5% of parent font size
  • lg (large): 125% of parent font size
  • xl (extra large): 150% of parent font size
  • 2xl (double extra large): 187.5% of parent font size
  • 3xl (triple extra large): 225% of parent font size
  • 4xl (quadruple extra large): 300% of parent font size
Copy Code
<nys-icon name="upload_file" size="2xs"></nys-icon>
<nys-icon name="upload_file" size="lg"></nys-icon>
<nys-icon name="upload_file" size="4xl"></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
  • 16: 1rem = 16px
  • 24: 1.5rem = 24px
  • 32: 2rem = 32px
  • 48: 3rem = 48px
  • 64: 4rem = 64px
Copy Code
<nys-icon name="upload_file" size="16"></nys-icon>
<nys-icon name="upload_file" size="32"></nys-icon>
<nys-icon name="upload_file" size="64"></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

Copy Code
<nys-icon ariaLabel="Upload file icon" name="upload_file" color="#db117d" size="4xl"></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.

Copy Code
<nys-icon rotate="20" ariaLabel="Upload file icon" name="upload_file" size="4xl"></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.

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

Usage

General

account_circle
calendar_month
cancel
check
close
download
download_done
drive_folder_upload
edit_square
help
language
link
mail
menu
more_vert
open_in_new
publish
search
share
sms
thumb_down
thumb_up
upload_file
visibility
visibility_off
notifications
add
remove
content_copy

Social

social_facebook
social_flickr
social_google_play
social_instagram
social_linkedin
social_pinterest
social_rss
social_snapchat
social_soundcloud
social_tiktok
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

When to use this component

  • Draw attention to actions. Icons, when paired with text, grab attention and show actions to take. Make sure each icon directly relates to any text it accompanies.
  • Help readers find key information. Use icons as scannable, easy-to-understand visual cues for key information, like a phone number or email address.
  • To provide recognizable visual representations for common actions or objects (e.g., search, download, social media links).
  • Enhance an actionable target. Icons increase the size of a button, which makes those buttons easier to click. Use an icon for common actions, like opening a menu or sharing an article.
  • Ideal for enhancing navigation menus, buttons, or other interactive elements with visual cues.

When to consider something else

  • Ambiguous meaning. Use icons only in a common or conventional way. Icon utility hinges on people quickly recognizing what each icon means. If you suspect that an icon’s intent isn’t perfectly clear, consider removing it.
  • Page structure. Don’t rely on an icon to help draw attention to something important that’s otherwise hard to find. Icons don’t fix unclear page hierarchy or confusing content organization.
  • If an icon does not add meaningful value to the context or might confuse users.
  • When a descriptive label or plain text provides clearer communication.
  • You need the icon to be focusable and clickable - in that case, use a <nys-button> component with an icon inside instead.

Do

  • Include a visual text label paired with the icon. 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 is focusable and conveys meaning, so screen readers can announce its purpose.
  • Align icons properly with text, both visually and semantically.
  • Use icons from the NYSDS library; if unavailable, use Google Material Symbols (rounded, unfilled).
  • Match icon size and color to the design system.
  • Test icon clarity with real users when possible.

Don't

  • Don’t overuse icons. Too many create visual noise and reduce focus.
  • Don’t replace meaningful text with icons unless the icon is universally recognized or paired with a label.
  • Don’t use standalone icons for actions. Use an icon button instead.
  • Avoid excessive icon customization that breaks design consistency.

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 a ariaLabel is provided, the component automatically adds an aria-label attribute, making the icon accessible to screen readers.


Properties

Property Type
ariaLabel String
color String (CSS HEX, CSS color name, or CSS variable)
flip "horizontal" | "vertical" | "both"
name String
rotate integer
size "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "12" | "16" | "24" | "32" | "48" | "64"

CSS Variables


Events

Suggest a New Component

Do you have an idea for a new NYSDS 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: August 22, 2025