Icon

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

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

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
  • 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

Example 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

Example 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

Example Code 
<nys-icon label="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, like rotate="20" (without "deg").

Example Code 
<nys-icon rotate="20" label="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.

Example Code 
<nys-icon flip="horizontal" label="upload_file icon" name="upload_file" size="4xl"></nys-icon>

Usage

General

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

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

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.

Do

  • Include a visual text label paired with the icon; only a very few icons are consistently understood universally across the digital-using public of the world; among them a house for home, printer for printing, and magnifying glass for search. Combine icons with text to improve clarity.
  • Be consistent with icon meaning. When an icon appears multiple times within a page or across pages of an application, it should represent the same concept and have identical text descriptions in every instance. For example, if a blank paper icon means "new document" across most screens, don't use it to mean "reformat document" elsewhere. This consistency benefits users with cognitive disabilities, helps those who may be distracted or scanning the page, and improves the overall user experience.
  • Align icons vertically with accompanying typography.
  • Prefer icons that are included in the NYSDS icon library; use Google Material Symbol rounded unfilled icons if you must use an icon not in the library. If you have a need for an icon not in the library, please contact the NYSDS Design System team in MS Teams NYSDS Troubleshooting channel for advisement on which icon is best for your use case.
  • Test icons for recognition and memorability with representative users of your application or website.
  • Use icons to enhance user interfaces with clear, recognizable icons.
  • Use appropriate icons align with the purpose and context of the UI elements they accompany.
  • [Dev] Provide an accessible label using the label attribute to ensure screen readers can interpret the icon's purpose (if warranted).
  • Customize icon sizes and colors to match the design system.

Don't

  • Don't overuse icons; too many icons on a page can create visual noise and makes it difficult for the user to focus.
  • Replace meaningful text with an icon unless its meaning is universally recognized or accompanied by a text label.
  • Use excessive customization that distracts from UI and established design patterns.

Accessibility

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

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

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


Properties

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

CSS Variables


Events