Icon

An inline SVG icon from the USWDS sprite sheet. Renders a <svg> element referencing the named icon from the bundled sprite. Follows USWDS icon patterns.

Props

Prop	Default	Description
`icon`		Name of the icon from the USWDS sprite (e.g., `search`, `close`, `info`)
`class`	`usa-icon`	CSS class applied to the `<svg>` element

Example Usage

Basic Icon

<c-icon icon="search" />

Icon with Custom Class

<c-icon icon="close" class="usa-icon usa-icon--size-3" />

Icon Inside a Button

<button class="usa-button" type="button">
    <c-icon icon="add" />
    Add item
</button>

Icon Used as a Decorative Element in Text

<p>
    <c-icon icon="info" />
    This information is important.
</p>

Available Icon Names

The USWDS sprite includes icons such as: accessibility_new, account_balance, add, alarm, arrow_back, arrow_forward, calendar_today, cancel, check, check_circle, close, credit_card, delete, directions, download, edit, error, event, facebook, file_download, flag, folder, github, help, home, info, instagram, launch, link, linkedin, lock, login, logout, mail, map, menu, navigate_before, navigate_next, notifications, people, person, phone, print, public, remove, rss_feed, save_alt, search, security, send, settings, share, star, support, twitter, upload_file, verified, visibility, warning, work, youtube, zoom_in, zoom_out, and many more.

See the pattern library Icon component page for a full visual listing of all available icons.

Usage Notes

Icons are aria-hidden="true" and focusable="false" by default, making them decorative
When an icon conveys meaning without accompanying text, add a visually hidden <span class="usa-sr-only"> label nearby for screen reader users
Use USWDS size utility classes (e.g., usa-icon--size-3, usa-icon--size-4) via the class prop to scale the icon

{% load static %}
<div role="region" aria-atomic="true">
  <label for="icon-filter">Type to filter icons</label>
  <input
    class="usa-input"
    id="icon-filter"
    onkeyup="filter(this)"
  />
  <p class="text-base" aria-live="polite">
    <span id="icon-count">243 icons.</span> Click an icon to copy its code
    snippet.
  </p>
</div>
<div class="display-flex flex-wrap margin-top-5">
  {% for variant in variants %}
  {% for icon in variant.icons %}
  <div
    role="region"
    aria-atomic="true"
    class="font-sans-xl position-relative icon-example border-1px border-base-lighter hover:text-white hover:bg-primary-vivid hover:border-primary-darker"
    data-meta="{{ icon.name }}"
    aria-label="{{ icon.name }} icon."
  >
    <button
      type="button"
      onclick="copyHTML(this)"
      class="bg-transparent cursor-pointer text-no-underline text-black display-flex width-card height-card flex-align-center flex-align-center border-0 flex-column flex-justify-center padding-2 hover:text-white"
      aria-label="Copy icon to clipboard"
      style="
        -webkit-user-select: text;
        -moz-user-select: text;
        -ms-user-select: text;
        user-select: text;
      "
    >
      {% cotton icon icon="{{ icon.name }}" %}{% endcotton %}
      <span class="font-sans-3xs margin-top-2 display-block" aria-hidden="true"
        >{{ icon.name }}</span
      >
    </button>
    <span
      aria-live="assertive"
      style="pointer-events: none"
      class="message-holder bottom-1 position-absolute font-sans-3xs text-bold display-block text-center left-0 width-full"
    ></span>
  </div>
  {% endfor %}
  {% endfor %}
</div>
<script>
  function filter(e) {
    search = e.value.toLowerCase();
    document.querySelectorAll(".icon-example").forEach(function (row) {
      text = row.getAttribute("data-meta").toLowerCase();
      if (text.match(search)) {
        row.classList.remove("display-none");
      } else {
        row.classList.add("display-none");
      }
    });
    iconCount = document.querySelectorAll(
      ".icon-example:not(.display-none)",
    ).length;
    var word = iconCount === 1 ? "icon" : "icons";
    document.getElementById("icon-count").innerHTML = `${iconCount} ${word}.`;
  }

  function copyHTML(el) {
    code = el.querySelector("svg").outerHTML;
    messagePlaceholder = el.nextElementSibling;
    oldCopyNotice = document.getElementById("icon-copy-notice");

    if (oldCopyNotice) {
      oldCopyNotice.remove();
    }

    message = document.createElement("span");
    message.setAttribute("id", "icon-copy-notice");
    message.classList.add("bg-primary", "text-white", "padding-1", "border-radius-2px");
    message.innerHTML = "Copied to clipboard!";

    // Copy the SVG code to clipboard
    var textArea = document.createElement("textarea");
    textArea.value = code;
    document.body.appendChild(textArea);
    textArea.select();
    document.execCommand('copy');
    document.body.removeChild(textArea);

    messagePlaceholder.append(message);
  }
</script>

name: Icon
context:
  variants:
    - title: "All Icons"
      type: "all"
      icons:
        - name: accessibility_new
        - name: accessible_forward
        - name: account_balance
        - name: account_box
        - name: account_circle
        - name: add
        - name: add_circle
        - name: add_circle_outline
        - name: alarm
        - name: alternate_email
        - name: announcement
        - name: arrow_back
        - name: arrow_downward
        - name: arrow_drop_down
        - name: arrow_drop_up
        - name: arrow_forward
        - name: arrow_upward
        - name: api
        - name: assessment
        - name: attach_file
        - name: attach_money
        - name: autorenew
        - name: backpack
        - name: bathtub
        - name: bedding
        - name: bookmark
        - name: bug_report
        - name: build
        - name: calendar_today
        - name: campaign
        - name: camping
        - name: cancel
        - name: chat
        - name: check
        - name: check_box_outline_blank
        - name: check_circle
        - name: check_circle_outline
        - name: checkroom
        - name: clean_hands
        - name: clothes
        - name: close
        - name: closed_caption
        - name: cloud
        - name: code
        - name: comment
        - name: connect_without_contact
        - name: construction
        - name: construction_worker
        - name: contact_page
        - name: content_copy
        - name: coronavirus
        - name: credit_card
        - name: deck
        - name: delete
        - name: device_thermostat
        - name: directions
        - name: directions_bike
        - name: directions_bus
        - name: directions_car
        - name: directions_walk
        - name: do_not_disturb
        - name: do_not_touch
        - name: drag_handle
        - name: eco
        - name: edit
        - name: electrical_services
        - name: emoji_events
        - name: error
        - name: error_outline
        - name: event
        - name: expand_less
        - name: expand_more
        - name: facebook
        - name: fast_forward
        - name: fast_rewind
        - name: favorite
        - name: favorite_border
        - name: fax
        - name: file_download
        - name: file_present
        - name: file_upload
        - name: filter_alt
        - name: filter_list
        - name: fingerprint
        - name: first_page
        - name: flag
        - name: flickr
        - name: flight
        - name: flooding
        - name: folder
        - name: folder_open
        - name: format_quote
        - name: format_size
        - name: forum
        - name: github
        - name: grid_view
        - name: group_add
        - name: groups
        - name: hearing
        - name: help
        - name: help_outline
        - name: highlight_off
        - name: history
        - name: home
        - name: hospital
        - name: hotel
        - name: hourglass_empty
        - name: hurricane
        - name: identification
        - name: image
        - name: info
        - name: info_outline
        - name: insights
        - name: instagram
        - name: keyboard
        - name: label
        - name: language
        - name: last_page
        - name: launch
        - name: lightbulb
        - name: lightbulb_outline
        - name: link
        - name: link_off
        - name: linkedin
        - name: list
        - name: local_cafe
        - name: local_fire_department
        - name: local_gas_station
        - name: local_grocery_store
        - name: local_hospital
        - name: local_laundry_service
        - name: local_library
        - name: local_offer
        - name: local_parking
        - name: local_pharmacy
        - name: local_police
        - name: local_taxi
        - name: location_city
        - name: location_on
        - name: lock
        - name: lock_open
        - name: lock_outline
        - name: login
        - name: logout
        - name: loop
        - name: mail
        - name: mail_outline
        - name: map
        - name: masks
        - name: medical_services
        - name: menu
        - name: military_tech
        - name: more_horiz
        - name: more_vert
        - name: my_location
        - name: navigate_before
        - name: navigate_next
        - name: navigate_far_before
        - name: navigate_far_next
        - name: near_me
        - name: notifications
        - name: notifications_active
        - name: notifications_none
        - name: notifications_off
        - name: park
        - name: people
        - name: person
        - name: pets
        - name: phone
        - name: photo_camera
        - name: print
        - name: priority_high
        - name: public
        - name: push_pin
        - name: radio_button_unchecked
        - name: rain
        - name: reduce_capacity
        - name: remove
        - name: remove_circle
        - name: report
        - name: restaurant
        - name: rss_feed
        - name: safety_divider
        - name: sanitizer
        - name: severe_weather
        - name: save_alt
        - name: schedule
        - name: school
        - name: science
        - name: search
        - name: security
        - name: send
        - name: sentiment_dissatisfied
        - name: sentiment_neutral
        - name: sentiment_satisfied
        - name: sentiment_satisfied_alt
        - name: sentiment_very_dissatisfied
        - name: settings
        - name: share
        - name: shield
        - name: shopping_basket
        - name: snow
        - name: soap
        - name: social_distance
        - name: sort_arrow
        - name: spellcheck
        - name: star
        - name: star_half
        - name: star_outline
        - name: store
        - name: support
        - name: support_agent
        - name: text_fields
        - name: thumb_down_alt
        - name: thumb_up_alt
        - name: timer
        - name: toggle_off
        - name: toggle_on
        - name: topic
        - name: tornado
        - name: translate
        - name: trending_down
        - name: trending_up
        - name: twitter
        - name: undo
        - name: unfold_less
        - name: unfold_more
        - name: update
        - name: upload_file
        - name: verified
        - name: verified_user
        - name: visibility
        - name: visibility_off
        - name: volume_off
        - name: warning
        - name: wash
        - name: wifi
        - name: work
        - name: x
        - name: youtube
        - name: zoom_in
        - name: zoom_out_map
        - name: zoom_out