Skip to main content Design tokens Components Style utilities
Skip to table of contents

    Icon

    Icons are visual symbols that represent actions, objects or ideas.

    Placer Toolkit comes bundled with over 2,000 free icons courtesy of Font Awesome. These icons are part of the default icon library. If you prefer, you can register custom icon libraries as well as Font Awesome Pro.

    Not sure which icon to use? Find the perfect icon over at Font Awesome!

    Demos

    Icon styles

    The default icon library uses Font Awesome Free, which comes with three icon styles: Solid, Regular and Brands. Font Awesome Pro is available by creating a custom icon library dedicated to Font Awesome Pro.

    Colours

    Icons inherit their colour from the current text colour. Thus, you can set the color property on the <pc-icon> element or an ancestor to change the colour.

    Sizes

    Icons are sized relative to the current font size. To change the size of an icon, set the font-size property on the icon itself or on a parent element as shown below.

    Labels

    For non‐decorative icons, use the label attribute to announce the label’s content to assistive devices.

    Fixed‐width icons

    By default, Font Awesome icons have a pixel grid of 16×16px with the width having an extra 4px overflow to account for wider icons. To make icons have a fixed width, use the fixed-width attribute to render the icon in a 20×20px grid.

    Images

    Images that are supposed to act like icons can be loaded individually with the src attribute. Only SVGs on a local or CORS‐enabled endpoint are supported. If you’re using more than one custom icon, it might make sense to register a custom icon library instead.

    Defining a custom icon library

    You can register additional icons to use with the <pc-icon> component through custom icon libraries. Icon files can exist locally or on a CORS‐enabled endpoint (e.g., a CDN). There is no limit to how many custom icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they’re used.

    Placer Toolkit ships with two built‐in icon libraries, default and system. The default icon library contains all icons in Font Awesome Free. The system icon library only contains a subset of icons in Font Awesome Free that are used internally by Placer Toolkit components.

    To register a custom icon library, use the registerIconLibrary() function exported from utilities/icon-library.js. At a minimum, you must provide a name and a resolver function. The resolver function translates an icon name to a URL where the corresponding SVG file exists. Refer to the examples below to better understand how it works.

    Here’s an example that registers an icon library located in the /assets/icons directory.

    <script type="module">
  import { registerIconLibrary } from "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/utilities/icon-library.js";

  registerIconLibrary("custom-icon-library", {
      resolver: (name) => `/assets/icons/${name}.svg`,
  });
</script>

    To display an icon, set the library and name attributes of a <pc-icon> element. The icon-style attribute is not set up for custom icon libraries by default, as it’s designed for the default icon library.

    <!-- This will show the icon located at /assets/icons/face-smile.svg -->
<pc-icon library="custom-icon-library" name="face-smile"></pc-icon>

    If an icon is used, before registration occurs, it will be initially empty, but shown when it gets registered.

    The following examples demonstrate how to register a number of popular, open‐source icon libraries via the CDN. Feel free to adapt the code as you see fit to use your own origin or naming conventions.

    Font Awesome Pro

    This sets up the Font Awesome icon library using a Kit. Head over to Font Awesome to create one, then swap out 42deadbeef with your own Kit code. Double‐check if your Kit is set to use Font Awesome Pro to use Pro icons and features.

    <div style="font-size: var(--pc-font-size-xl)">
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="robot"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="cookie-bite"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="gamepad-modern"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="floppy-disk"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="server"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="solid"
      name="wine-glass"
  ></pc-icon>

  <br />

  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="robot"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="cookie-bite"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="gamepad-modern"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="floppy-disk"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="server"
  ></pc-icon>
  <pc-icon
      library="fa-pro"
      icon-style="regular"
      name="wine-glass"
  ></pc-icon>
  <!-- More icons still need to be added! -->
</div>

<script type="module">
  import { registerIconLibrary } from "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/utilities/icon-library.js";

  registerIconLibrary("fa-pro", {
      resolver: (name, iconStyle = "solid") => {
          return `https://ka-p.fontawesome.com/releases/v6.7.2/svgs/${iconStyle}/${name}.svg/?token=42deadbeef`;
      },
  });
</script>

    This page will include a bunch of icon libraries and will take a few versions to complete. Please be patient!

    Properties

    NameDescriptionReflectsDefault
    nameThe name of the icon to render. Available names depend on the icon library being used. string | undefined-
    iconStyle
    icon-style    		The icon style to use for the icon. If not configured, this only works for the default and Font Awesome Pro icon libraries. string | undefined-
    fixedWidth
    fixed-width    		Sets the width of the icon to 1.25em (20px) and centres it. It’s similar to the Font Awesome class fa-fw. booleanfalse
    swapOpacity
    swap-opacity    		Swaps the opacity of duotone icons. Has no effect on icon libraries that aren’t the default one or Font Awesome Pro one. booleanfalse
    srcThe external URL of an SVG file. Make sure you trust the content you are included, as it will be executed as code and can result in XSS attacks. string | undefined-
    labelA label to include for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. string""
    libraryThe name of a registered icon library. string"default"
    updateComplete A read‐only promise that resolves when the component has finished updating. -

    Learn more about attributes and properties.

    Events

    NameDescriptionEvent detail
    pc-loadEmitted when the icon has loaded. When using spriteSheet: true, this will not emit.-
    pc-errorEmitted when the icon fails to load due to an error. When using spriteSheet: true, this will not emit.-

    Learn more about events.

    Custom properties

    NameDescriptionDefault
    --fa-primary-colorThe primary colour for the primary layer in duotone icons.-
    --fa-secondary-colorThe secondary colour for the secondary layer in duotone icons.-
    --fa-primary-opacityThe primary opacity for the primary layer in duotone icons.-
    --fa-secondary-opacityThe secondary opacity for the secondary layer in duotone icons.-

    Learn more about customising custom properties.

    Parts

    NameDescription
    svgThe component’s internal SVG element.
    useThe <use> element generated when using spriteSheet: true.

    Learn more about customising CSS parts.

    Importing

    If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

    ScriptImportBundler

    To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML. 

    <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/icon/icon.js"></script>

    To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript: 

    import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/icon/icon.js";

    To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript: 

    import "placer-toolkit/dist/components/icon/icon.js";