The Placer Toolkit alpha has
arrived! 🎉
Plenty of changes are coming your
way—some big, some breaking, some
even nuclear! Beware the changelog…
Icon
<pc-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. If you’re a Font Awesome Pro user, you can provide your Kit code to unlock Pro icon packs and styles.
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.
Auto‐width icons#
By default, Font Awesome icons have a 1em height and a fixed 1em width. Use the auto-width attribute to allow the icon to use its natural variable width.
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@1.0.0-alpha.1/cdn/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 and system icon libraries.
<!-- 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.
Properties#
| Name | Description | Reflects | Default |
|---|---|---|---|
name | The name of the icon to render. Available names depend on the icon library being used. Type: string | undefined |
| ‐ |
iconStyleicon-style | The icon style to use for the icon. If not configured, this only works for the default icon library. Type: string |
| "solid" |
autoWidthauto-width | Sets the width of the icon to match the cropped SVG viewBox. This operates like the Font Awesome fa-width-auto class.Type: boolean |
| false |
swapOpacityswap-opacity | Swaps the opacity of duotone icons. Has no effect on custom icon libraries. Type: boolean |
| false |
src | The 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. Type: string | undefined |
| ‐ |
label | A label to include for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. Type: string |
| "" |
library | The name of a registered icon library. Type: string |
| "default" |
updateComplete | A read‐only promise that resolves when the component has finished updating. | ‐ |
Learn more about attributes and properties.
Events#
| Name | Description | Event detail |
|---|---|---|
pc-load | Emitted when the icon has loaded. When using spriteSheet: true, this will not emit. | ‐ |
pc-error | Emitted when the icon fails to load due to an error. When using spriteSheet: true, this will not emit. | ‐ |
Learn more about events.
Custom properties#
| Name | Description | Default |
|---|---|---|
--fa-primary-color | The primary colour for the primary layer in duotone icons. | currentColor |
--fa-secondary-color | The secondary colour for the secondary layer in duotone icons. | currentColor |
--fa-primary-opacity | The primary opacity for the primary layer in duotone icons. | 1 |
--fa-secondary-opacity | The secondary opacity for the secondary layer in duotone icons. | 0.4 |
Learn more about customising custom properties.
Parts#
| Name | Description |
|---|---|
svg | The component’s internal SVG element. |
use | The <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 skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.
To manually import this component from the CDN, copy this code snippet and paste it in your HTML.
<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/icon/icon.js"></script>To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.
import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/icon/icon.js";To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.
import "placer-toolkit/dist/components/icon/icon.js";