Shoelace Feature Options (options)
Platen is in the process of more closely integrating the excellent set of web components from Shoelace into the site theme. This gives you a set of very configurable and customizable components to use on your site and in your markup.
JSON Schema
Definition
{
"$id": "https://platen.io/schemas/platen/site/features/shoelace/options/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Settings that control the site's integration with Shoelace.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/",
"properties": {
"always_load": {
"default": true,
"description": "Choose whether the link to the Shoelace library is always added to every page.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#always_load",
"title": "Always Load Shoelace",
"type": "boolean"
},
"enabled": {
"default": true,
"description": "Choose whether Platen integrates with Shoelace.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#enabled",
"title": "Enable Shoelace",
"type": "boolean"
},
"icons": {
"description": "Settings for Shoelace's icons.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#icons",
"properties": {
"always_load_libraries": {
"default": [],
"description": "Define any number of libraries to always register and load for a page.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#always_load_libraries",
"items": {
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
],
"type": "string"
},
{
"type": "string"
}
]
},
"title": "Always Load Libraries List",
"type": "array"
},
"default_library": {
"default": "builtin_bootstrap",
"description": "Sets the default icon library for your site.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#default_library",
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
],
"type": "string"
},
{
"type": "string"
}
],
"title": "Default Icon Library"
},
"libraries": {
"description": "Controls the settings for various known icon libraries.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#libraries",
"properties": {
"boxicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/boxicons/schema.json"
},
"builtin_bootstrap": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/default/schema.json"
},
"font_awesome": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/font_awesome/schema.json"
},
"heroicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/heroicons/schema.json"
},
"iconoir": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/iconoir/schema.json"
},
"ionicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/ionicons/schema.json"
},
"jam_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/jam_icons/schema.json"
},
"lucide": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/lucide/schema.json"
},
"material_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/material_icons/schema.json"
},
"remix_icon": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/remix_icon/schema.json"
},
"tabler_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/tabler_icons/schema.json"
},
"unicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/unicons/schema.json"
}
},
"title": "Icon Library Settings",
"type": "object"
}
},
"title": "Shoelace Icon Options",
"type": "object"
},
"partials": {
"description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#partials",
"properties": {
"header": {
"default": "platen/features/shoelace/header",
"description": "Injects a partial into the HTML header.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#header",
"title": "Header Partial",
"type": "string"
}
},
"title": "Feature Partials",
"type": "object"
},
"version": {
"default": "2.4.0",
"description": "Choose the version of Shoelace to load.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#version",
"title": "Shoelace Version",
"type": "string"
}
},
"title": "Shoelace Feature Options",
"type": "object"
}Enable Shoelace (enabled)
Choose whether the site can use Shoelace web components. The default is true.
If you disable the Shoelace web components, you may need to radically update the markup and layout for Platen.
Always Load Shoelace (always_load)
Use this setting to choose whether the link to the Shoelace library should be added to every page. Platen uses Shoelace’s autoloading feature, which means that it only retrieves code from Shoelace on an as-needed basis.
We strongly recommend leaving this option set to true to minimize complexity. This allows you to use any
Shoelace components in your own markdown or special markup without needing to add handlers to cherry pick the
components yourself.
Shoelace Version (version)
Use this setting to choose the version of Shoelace to load for your site. Platen regularly updates this version
after testing. You can override it to specify an earlier version or set this value to latest to always
retrieve the latest released version.
Shoelace Icon Options (icons)
Platen supports automatic registration and easier use of icons through Shoelace. It has built-in support for a dozen different icon libraries.
JSON Schema
Definition
{
"description": "Settings for Shoelace's icons.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/",
"properties": {
"always_load_libraries": {
"default": [],
"description": "Define any number of libraries to always register and load for a page.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#always_load_libraries",
"items": {
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
],
"type": "string"
},
{
"type": "string"
}
]
},
"title": "Always Load Libraries List",
"type": "array"
},
"default_library": {
"default": "builtin_bootstrap",
"description": "Sets the default icon library for your site.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#default_library",
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
],
"type": "string"
},
{
"type": "string"
}
],
"title": "Default Icon Library"
},
"libraries": {
"description": "Controls the settings for various known icon libraries.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/#libraries",
"properties": {
"boxicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/boxicons/schema.json"
},
"builtin_bootstrap": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/default/schema.json"
},
"font_awesome": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/font_awesome/schema.json"
},
"heroicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/heroicons/schema.json"
},
"iconoir": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/iconoir/schema.json"
},
"ionicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/ionicons/schema.json"
},
"jam_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/jam_icons/schema.json"
},
"lucide": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/lucide/schema.json"
},
"material_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/material_icons/schema.json"
},
"remix_icon": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/remix_icon/schema.json"
},
"tabler_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/tabler_icons/schema.json"
},
"unicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/unicons/schema.json"
}
},
"title": "Icon Library Settings",
"type": "object"
}
},
"title": "Shoelace Icon Options",
"type": "object"
}Default Icon Library (default_library)
You can use this setting to use a different icon library by default. As long as this setting maps to the name or alias of a registered library, Platen will use that library by default for its markup and any icons you specify for theme components.
Always Load Libraries List (always_load_libraries)
Use this setting to create a list of icon libraries that Platen should always load, even when the icons aren’t used in Platen’s markup or a theme component. This is mostly useful if you’re using inline Shoelace components or adding your own markup outside of Platen’s configuration.
By default, Platen checks any specified icon in your markup or theme components and maintains a list of icon libraries to register for each page on your behalf. You can freely use the configured libraries without having to ensure they register.
Icon Library Settings (libraries)
These settings control the registration and behavior for icon libraries to use in Shoelace web components for Platen. Platen provides default configuration and registration for a dozen different icon libraries.
You can also define your own icon libraries to register with Platen. For now, see the implementations for the existing libraries. You can reach out to the maintainers if you have questions or want another library added to the built-in supported libraries.
JSON Schema
Definition
{
"description": "Controls the settings for various known icon libraries.\n\nhttps://platen.io/schemas/platen/site/features/shoelace/options/",
"properties": {
"boxicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/boxicons/schema.json"
},
"builtin_bootstrap": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/default/schema.json"
},
"font_awesome": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/font_awesome/schema.json"
},
"heroicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/heroicons/schema.json"
},
"iconoir": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/iconoir/schema.json"
},
"ionicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/ionicons/schema.json"
},
"jam_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/jam_icons/schema.json"
},
"lucide": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/lucide/schema.json"
},
"material_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/material_icons/schema.json"
},
"remix_icon": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/remix_icon/schema.json"
},
"tabler_icons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/tabler_icons/schema.json"
},
"unicons": {
"$ref": "https://platen.io/schemas/platen/site/features/shoelace/icon_libraries/unicons/schema.json"
}
},
"title": "Icon Library Settings",
"type": "object"
}Builtin Bootstrap Icons Library (builtin_bootstrap)
These options control the default icon library used by Shoelace. Shoelace makes 1,500 icons from the Bootstrap Icons project available.
For more information, see Builtin Bootstrap Icons Library
Iconoir (iconoir)
These options control the registration of the Iconoir library.
Iconoir uses the MIT License.
For more information, see Iconoir
Heroicons (heroicons)
These options control the registration of the Heroicons library.
Heroicons uses the MIT License.
For more information, see Heroicons
Tabler Icons (tabler_icons)
These options control the registration of the Tabler Icons library.
Tabler Icons uses the MIT License.
For more information, see Tabler Icons
Ionicons (ionicons)
These options control the registration of the Ionicons library.
Ionicons uses the MIT License.
For more information, see Ionicons
Boxicons (boxicons)
These options control the registration of the Boxicons library.
Boxicons uses the Creative Commons 4.0 License.
For more information, see Boxicons
Jam Icons (jam_icons)
These options control the registration of the Jam Icons library.
Jam Icons uses the MIT License.
For more information, see Jam Icons
Lucide (lucide)
These options control the registration of the Lucide library.
Lucide uses the MIT License.
For more information, see Lucide
Font Awesome (font_awesome)
These options control the registration of the Font Awesome free library.
Font Awesome uses the Font Awesome Free License.
For more information, see Font Awesome
Unicons (unicons)
These options control the registration of the Unicons library.
Unicons uses the Apache 2.0 License.
Icons that require a specific license aren’t included in the default registration.
For more information, see Unicons
Material Icons (material_icons)
These options control the registration of the Material Icons library.
Material Icons uses the Apache 2.0 License.
For more information, see Material Icons
Remix Icon (remix_icon)
These options control the registration of the Remix Icon library.
Remix Icon uses the Apache 2.0 License.
For more information, see Remix Icon
Feature Partials (partials)
Define a map of partials for Platen to inject as needed. These partials are only
injected when enabled is set to true.
Header Partial (header)
If specified, this partial is processed in the HTML header with the current page’s context. The default
value is platen/features/shoelace/header. You can overwrite this value, replacing it with another partial
entirely, or you can add the same file to your own theme or site, effectively replacing it.
The default partial loads Shoelace from the CDN for use. It also adds a helper script, called modeSwap.js
from assets/scripts/shoelace/modeSwap.js, which helps support automatic theming between light and dark
modes. Finally, it sets up registration for Shoelace’s icon libraries.