The Placer Toolkit alpha has
arrived! 🎉
Plenty of changes are coming your
way—some big, some breaking, some
even nuclear! Beware the changelog…
Installation
You can load Placer Toolkit via the CDN or by installing it locally. We have many options to install Placer Toolkit depending on what setup you have.
CDN installation#
The experimental autoloader is the easiest and most efficient way to use Placer Toolkit. A lightweight script watches the DOM for unregistered Placer Toolkit elements and lazy‐loads them for you—even if they’re added dynamically.
While convenient, autoloading may lead to a Flash of Undefined Custom Elements (FOUCE). Add the pc-cloak class to the root HTML element to apply the FOUCE patch globally.
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/styles/placer.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/placer-autoloader.js"></script>The standard loader registers all web components in Placer Toolkit up front. If you’re only using a handful of components though, it will be much more efficient to stick with the autoloader. Alternatively, you can also cherry pick components if you only want to import specific ones up front. Remember to add the pc-cloak class to the root HTML element to apply the FOUCE patch globally.
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/styles/placer.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/placer.js"></script>Now you can start using Placer Toolkit!
Using Font Awesome Kit codes#
Font Awesome Pro and Pro+ users can set their Kit code to unlock the premium set of icons. You can provide it by adding the data-fa-kit-code attribute to any element on the page or by calling the setKitCode() function.
<!-- Option 1: The data-fa-kit-code attribute -->
<script
type="module"
src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/placer-autoloader.js"
data-fa-kit-code="42deadbeef"
></script>
<!-- Option 2: The setKitCode() function -->
<script type="module">
import { setKitCode } from "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/utilities/kit-code.js";
setKitCode("42deadbeef");
</script>Font Awesome Free icons are fetched from jsDelivr, which is GDPR compliant. Font Awesome Pro and Pro+ icons are fetched from Font Awesome’s Kit CDN, which sends users’ IP addresses to Font Awesome’s servers to count pageviews. IP addresses are considered personal data under GDPR.
If you use FA Pro/Pro+, you are responsible for:
- Disclosing this in your website’s privacy policy
- Ensuring compliance with GDPR and other privacy laws
- Having a valid legal basis for this data processing
See the Placer Toolkit privacy policy for more information.
Advanced setup#
The autoloader is the easiest way to use Placer Toolkit, but different projects (or your own preferences) may require different installation methods.
Cherry picking from the CDN#
Cherry picking will only load the components you need up front, while limiting the number of files the browser has to download. The disadvantage is that you need to import each individual component on each page it’s used. Additionally, you must include placer.css or other CSS files to style any imported components.
Here’s an example that only loads the Button component.
<link rel="stylesheet" href="https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/styles/placer.css" />
<script type="module">
import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.1/cdn/components/button/button.js";
// <pc-button> is registered and ready to use!
</script>You can copy and paste the code to import a code from the Importing section of that component’s documentation. Note that some components have dependencies that are automatically imported when you cherry pick components. If a component has dependencies, they will be listed in the Dependencies section of its docs.
You will see files named chunk.[hash].js in the chunks directory. Never import these files directly, as they are automatically generated and change from version to version.
npm installation#
If you don’t or are unable to use the CDN, you can install Placer Toolkit from npm by installing it via the npm registry or using our provided tarball file.
If you want to use the npm registry, you can use this command to install the package.
npm install placer-toolkityarn add placer-toolkitpnpm add placer-toolkitThis will install the latest version in your project.
Once you’ve done that, import the components you need.
// Import default fonts
import "https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap";
// Option 1: Import all Placer Toolkit styles
import "placer-toolkit/dist/styles/placer.css";
// Option 2: Only import the default theme
import "placer-toolkit/dist/styles/themes/default.css";
// Option 1: Import all components (may increase load times)
import "placer-toolkit";
// Option 2: Only import the components you need
// Import <pc-button>
import "placer-toolkit/dist/components/button/button.js";
// Import <pc-input>
import "placer-toolkit/dist/components/input/input.js";If you want to use the tarball file, download the tarball file into the root of your project first.
Then, install it from the tarball file with this command.
npm install placer-toolkit-1.0.0-alpha.1.tgzyarn add placer-toolkit-1.0.0-alpha.1.tgzpnpm add placer-toolkit-1.0.0-alpha.1.tgzOnce you’ve done that, import the components you need.
// Import default fonts
import "https://fonts.bunny.net/css?family=jetbrains-mono:100,100i,200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i|nunito:200,200i,300,300i,400,400i,500,500i,600,600i,700,700i,800,800i,900,900i|playfair-display:400,400i,500,500i,600,600i,700,700i,800,800i,900,900i&display=swap";
// Option 1: Import all Placer Toolkit styles
import "placer-toolkit/dist/styles/placer.css";
// Option 2: Only import the default theme
import "placer-toolkit/dist/styles/themes/default.css";
// Option 1: Import all components (may increase load times)
import "placer-toolkit";
// Option 2: Only import the components you need
// Import <pc-button>
import "placer-toolkit/dist/components/button/button.js";
// Import <pc-input>
import "placer-toolkit/dist/components/input/input.js";What’s the difference between cdn and dist?#
You’ll notice that the CDN links all start with /cdn/ and npm imports with /dist/. The /cdn/ files are bundled separately from the /dist/ files. The /cdn/ files come pre‐bundled, which means all dependencies are inlined, so you don’t need to worry about loading additional libraries. The /dist/ files do not come pre‐bundled, allowing your bundler of choice to more efficiently dedupe dependencies, resulting in smaller bundles and optimal code sharing.
TL;DR:
/cdn/is for CDN users/dist/is for npm users
This change was introduced in 1.0.0-alpha.1 to fix tslib bare module specifier errors in 0.5.1.