Icon

<pc-icon>

0.1.0

experimental

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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.

<pc-icon
    library="default"
    icon-style="solid"
    name="circle-info"
></pc-icon>
<pc-icon
    library="default"
    icon-style="solid"
    name="fire"
></pc-icon>
<pc-icon
    library="default"
    icon-style="solid"
    name="dumpster-fire"
></pc-icon>
<pc-icon
    library="default"
    icon-style="brands"
    name="github"
></pc-icon>

Code

Edit

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.

<div style="color: var(--pc-color-blue)">
    <pc-icon
        library="default"
        icon-style="solid"
        name="triangle-exclamation"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="box-archive"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="battery-three-quarters"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="bell"
    ></pc-icon>
</div>
<div style="color: var(--pc-color-purple)">
    <pc-icon
        library="default"
        icon-style="regular"
        name="clock"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="cloud"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="download"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="file"
    ></pc-icon>
</div>
<div style="color: var(--pc-color-green)">
    <pc-icon
        library="default"
        icon-style="solid"
        name="flag-checkered"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="heart"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="image"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="bolt"
    ></pc-icon>
</div>
<div style="color: var(--pc-color-yellow)">
    <pc-icon
        library="default"
        icon-style="solid"
        name="microphone"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="magnifying-glass"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="star"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="dumpster-fire"
    ></pc-icon>
</div>

Code

Edit

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.

<div style="font-size: 1.5em">
    <pc-icon
        library="default"
        icon-style="solid"
        name="triangle-exclamation"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="box-archive"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="battery-three-quarters"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="bell"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="regular"
        name="clock"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="cloud"
    ></pc-icon>
</div>

Code

Edit

Labels#

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

<pc-icon
    library="default"
    icon-style="solid"
    name="star"
    label="Add to favourites"
></pc-icon>

Code

Edit

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.

<strong>Without auto‐width</strong><br />
<div style="color: var(--pc-color-neutral-10); font-size: 1.5em">
    <pc-icon
        library="default"
        icon-style="solid"
        name="exclamation"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="circle-check"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="keyboard"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="ruler-vertical"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="ruler-horizontal"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="bullhorn"
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
</div>

<strong>With auto‐width</strong><br />
<div style="color: var(--pc-color-neutral-10); font-size: 1.5em">
    <pc-icon
        library="default"
        icon-style="solid"
        name="exclamation"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="circle-check"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="keyboard"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="ruler-vertical"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="ruler-horizontal"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
    <pc-icon
        library="default"
        icon-style="solid"
        name="bullhorn"
        auto-width
        style="background-color: var(--pc-color-danger-70)"
    ></pc-icon>
</div>

Code

Edit

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.

<pc-icon src="https://placer-toolkit.vercel.app/brand/logo.svg" style="font-size: 8rem"></pc-icon>

Code

Edit

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.3/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.

Eigenschaften#

Name	Beschreibung	Standard
`name`	The name of the icon to render. Available names depend on the icon library being used. Typ: `string \| undefined`	‐
`iconStyle` `icon-style`	The icon style to use for the icon. If not configured, this only works for the default icon library. Typ: `string`	`"solid"`
`autoWidth` `auto-width`	Sets the width of the icon to match the cropped SVG viewBox. This operates like the Font Awesome `fa-width-auto` class. Typ: `boolean`	`false`
`swapOpacity` `swap-opacity`	Swaps the opacity of duotone icons. Has no effect on custom icon libraries. Typ: `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. Typ: `string \| undefined`	‐
`label`	A label to include for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. Typ: `string`	`""`
`library`	The name of a registered icon library. Typ: `string`	`"default"`
`updateComplete`	Ein schreibgeschütztes Promise, das erfüllt ist, sobald die Komponente fertig aktualisiert wurde.	‐

Erfahre mehr über Attribute und Eigenschaften.

Events#

Name	Beschreibung	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.	‐

Erfahre mehr über Events.

Benutzerdefinierte Eigenschaften#

Name	Beschreibung	Standard
`--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`

Erfahre mehr über das Anpassen von benutzerdefinierten Eigenschaften.

Parts#

Name	Beschreibung
`svg`	The component’s internal SVG element.
`use`	The `<use>` element generated when using `spriteSheet: true`.

Erfahre mehr über das Anpassen von CSS‐Parts.

Importieren#

Wenn du den Autoloader oder den Standard‐Loader nutzt, kannst du diesen Abschnitt überspringen. Falls du „Cherry Picking“ betreibst, kannst du die folgenden Snippets verwenden, um diese Komponente zu importieren.

CDN (Skript‐Tag)

CDN (Import)

npm (Import)

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in dein HTML ein.

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

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/icon/icon.js"; 

Um diese Komponente manuell via npm zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

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