Site Mobile Display Settings (mobile)
The Platen display options control how the site displays on smaller screens.
JSON Schema
Definition
{
"$id": "https://platen.io/schemas/platen/site/display/mobile/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Optional settings controlling how a Platen mobile view displays.\n\nhttps://platen.io/schemas/platen/site/display/mobile/",
"properties": {
"menu_control": {
"description": "Controls the display for the button that shows the site menu on mobile.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#menu_control",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Icon Button Classes",
"type": "array"
},
"label": {
"default": "i18n!menu_control",
"description": "Defines the accessible label for the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#label",
"title": "Icon Button Label",
"type": "string"
},
"library": {
"description": "The library the icon is in.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#library",
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
]
},
{
"type": "string"
}
],
"title": "Icon Library"
},
"name": {
"default": "list@builtin_bootstrap",
"description": "The name of the icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#name",
"title": "Icon Name",
"type": "string"
},
"src": {
"description": "The source for a custom icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#src",
"title": "Icon SVG Source",
"type": "string"
},
"tooltip": {
"description": "Set options for the icon button's tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#tooltip",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Tooltip Classes",
"type": "array"
},
"content": {
"description": "The text to display for the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#content",
"title": "Tooltip Content",
"type": "string"
},
"distance": {
"description": "Sets how many pixels away from the icon button the tooltip renders.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#distance",
"minimum": 0,
"title": "Tooltip Distance",
"type": "integer"
},
"placement": {
"default": "right",
"description": "Where the tooltip renders in relation to the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#placement",
"enum": [
"top",
"top-start",
"top-end",
"right",
"right-start",
"right-end",
"bottom",
"bottom-start",
"bottom-end",
"left",
"left-start",
"left-end"
],
"title": "Tooltip Placement"
},
"skidding": {
"description": "Sets how many pixels to offset the tooltip from its defined placement along the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#skidding",
"title": "Tooltip Skidding",
"type": "integer"
}
},
"title": "Tooltip Options",
"type": "object"
},
"use_legacy": {
"default": true,
"description": "Choose whether to use the legacy SVG icon control or the configurable shoelace icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#use_legacy",
"title": "Use Legacy Menu Control",
"type": "boolean"
},
"variant": {
"description": "The icon variant.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#variant",
"title": "Icon Variant",
"type": "string"
}
},
"title": "Menu Control Button",
"type": "object"
},
"toc_control": {
"description": "Controls the display for the button that shows the TOC on mobile.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#toc_control",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Icon Button Classes",
"type": "array"
},
"label": {
"default": "i18n!toc_control",
"description": "Defines the accessible label for the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#label",
"title": "Icon Button Label",
"type": "string"
},
"library": {
"description": "The library the icon is in.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#library",
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
]
},
{
"type": "string"
}
],
"title": "Icon Library"
},
"name": {
"default": "list-columns@builtin_bootstrap",
"description": "The name of the icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#name",
"title": "Icon Name",
"type": "string"
},
"src": {
"description": "The source for a custom icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#src",
"title": "Icon SVG Source",
"type": "string"
},
"tooltip": {
"description": "Set options for the icon button's tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#tooltip",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Tooltip Classes",
"type": "array"
},
"content": {
"description": "The text to display for the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#content",
"title": "Tooltip Content",
"type": "string"
},
"distance": {
"description": "Sets how many pixels away from the icon button the tooltip renders.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#distance",
"minimum": 0,
"title": "Tooltip Distance",
"type": "integer"
},
"placement": {
"default": "left",
"description": "Where the tooltip renders in relation to the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#placement",
"enum": [
"top",
"top-start",
"top-end",
"right",
"right-start",
"right-end",
"bottom",
"bottom-start",
"bottom-end",
"left",
"left-start",
"left-end"
],
"title": "Tooltip Placement"
},
"skidding": {
"description": "Sets how many pixels to offset the tooltip from its defined placement along the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#skidding",
"title": "Tooltip Skidding",
"type": "integer"
}
},
"title": "Tooltip Options",
"type": "object"
},
"use_legacy": {
"default": true,
"description": "Choose whether to use the legacy SVG icon control or the configurable shoelace icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#use_legacy",
"title": "Use Legacy Table of Contents Control",
"type": "boolean"
},
"variant": {
"description": "The icon variant.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#variant",
"title": "Icon Variant",
"type": "string"
}
},
"title": "Table of Contents Control Button",
"type": "object"
}
},
"title": "Site Mobile Display Settings",
"type": "object"
}Table of Contents Control Button (toc_control)
Use these settings to control the display for the button that shows the table of contents on mobile. The button appears in the top right corner of each page beside the page’s title. When a visitor clicks it, the table of contents pops out from the right side of the screen.
At this time, the use_legacy setting for this control defaults to true, which makes Platen render your site
with the old control. The old control is not configurable. In the future, the default value for this control
will be updated to false. Later, the option to use the legacy control will be removed entirely.
We strongly recommend that you set use_legacy to false and update your site’s theme as needed.
JSON Schema
Definition
{
"description": "Controls the display for the button that shows the TOC on mobile.\n\nhttps://platen.io/schemas/platen/site/display/mobile/",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Icon Button Classes",
"type": "array"
},
"label": {
"default": "i18n!toc_control",
"description": "Defines the accessible label for the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#label",
"title": "Icon Button Label",
"type": "string"
},
"library": {
"description": "The library the icon is in.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#library",
"oneOf": [
{
"enum": [
"builtin_bootstrap",
"boxicons",
"font_awesome",
"heroicons",
"iconoir",
"ionicons",
"jam_icons",
"lucide",
"material_icons",
"remix_icon",
"tabler_icons",
"unicons"
]
},
{
"type": "string"
}
],
"title": "Icon Library"
},
"name": {
"default": "list-columns@builtin_bootstrap",
"description": "The name of the icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#name",
"title": "Icon Name",
"type": "string"
},
"src": {
"description": "The source for a custom icon.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#src",
"title": "Icon SVG Source",
"type": "string"
},
"tooltip": {
"description": "Set options for the icon button's tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#tooltip",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Tooltip Classes",
"type": "array"
},
"content": {
"description": "The text to display for the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#content",
"title": "Tooltip Content",
"type": "string"
},
"distance": {
"description": "Sets how many pixels away from the icon button the tooltip renders.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#distance",
"minimum": 0,
"title": "Tooltip Distance",
"type": "integer"
},
"placement": {
"default": "left",
"description": "Where the tooltip renders in relation to the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#placement",
"enum": [
"top",
"top-start",
"top-end",
"right",
"right-start",
"right-end",
"bottom",
"bottom-start",
"bottom-end",
"left",
"left-start",
"left-end"
],
"title": "Tooltip Placement"
},
"skidding": {
"description": "Sets how many pixels to offset the tooltip from its defined placement along the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#skidding",
"title": "Tooltip Skidding",
"type": "integer"
}
},
"title": "Tooltip Options",
"type": "object"
},
"use_legacy": {
"default": true,
"description": "Choose whether to use the legacy SVG icon control or the configurable shoelace icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#use_legacy",
"title": "Use Legacy Table of Contents Control",
"type": "boolean"
},
"variant": {
"description": "The icon variant.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#variant",
"title": "Icon Variant",
"type": "string"
}
},
"title": "Table of Contents Control Button",
"type": "object"
}Icon Name (name)
This setting specifies the name of the icon to display. You can specify the icon with Platen’s shorthand syntax for icons.
The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:
<name>is mandatory and represents the name of the icon.&<variant>is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.&<library>is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.
You can always use any valid icon in Shoelace’s default icon library.
If you specify the icon’s variant or library with the shorthand syntax, don’t specify the [sref:variant]
or [sref:library] settings for this icon.
The default icon for this setting is:
Icon Button Label (label)
This setting defines the accessible label for the icon button. A label helps users understand what a button without text does.
Specify a short plaintext message explaining what the button does. If you specify this value with the
prefix i18n!, like i18n!foo_bar, Platen looks up the value as a key in your site’s internationalization
settings to translate the value for the current language. This can help make your buttons more accessible
for multilingual sites.
Icon Library (library)
This setting specifies the library to load the icon from. You can use any of the registered icon libraries.
If you don’t specify a value for this setting, Platen uses the features.shoelace.icons.default_library
setting’s value as the library.
Don’t specify this setting if you’re including the library in the name setting with the shorthand syntax.
Icon Variant (variant)
This setting specifies the icon’s variant. Not all icons and libraries have variants. If this value isn’t set, the icon uses its default variant.
Don’t specify this setting if you’re including the variant in the name setting with the shorthand syntax.
Icon SVG Source (src)
This setting specifies the URL to an SVG file to use as a custom icon. If you specify this value, Platen
ignores the settings for the name, library, and variant settings.
Icon Button Classes (classes)
Use this setting to add CSS classes to the icon button. These classes can control how the icon is styled on the site separately from the configuration options.
Tooltip Options (tooltip)
Use these settings to control how the icon button’s tooltip displays. Icon buttons always have a tooltip to help make their usage more obvious to readers.
JSON Schema
Definition
{
"description": "Set options for the icon button's tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/",
"properties": {
"classes": {
"description": "One or more CSS classes to add to the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#classes",
"items": {
"type": "string"
},
"title": "Tooltip Classes",
"type": "array"
},
"content": {
"description": "The text to display for the tooltip.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#content",
"title": "Tooltip Content",
"type": "string"
},
"distance": {
"description": "Sets how many pixels away from the icon button the tooltip renders.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#distance",
"minimum": 0,
"title": "Tooltip Distance",
"type": "integer"
},
"placement": {
"default": "left",
"description": "Where the tooltip renders in relation to the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#placement",
"enum": [
"top",
"top-start",
"top-end",
"right",
"right-start",
"right-end",
"bottom",
"bottom-start",
"bottom-end",
"left",
"left-start",
"left-end"
],
"title": "Tooltip Placement"
},
"skidding": {
"description": "Sets how many pixels to offset the tooltip from its defined placement along the icon button.\n\nhttps://platen.io/schemas/platen/site/display/mobile/#skidding",
"title": "Tooltip Skidding",
"type": "integer"
}
},
"title": "Tooltip Options",
"type": "object"
}Tooltip Classes (classes)
Use this setting to add CSS classes to the tooltip. These classes can control how the tooltip is styled on the site separately from the configuration options.
Tooltip Content (content)
Use this setting to define a custom message to display for the tooltip. If this value isn’t defined, the tooltip displays the label text for the icon button.
If you specify this value with the prefix i18n!, like i18n!foo_bar, Platen looks up the value as a
key in your site’s internationalization settings to translate the value for the current language. This
can help make your tooltips more accessible for multilingual sites.
Tooltip Placement (placement)
Use this setting to define where the tooltip pops up in relation to the icon button.
The top, right, bottom, and left placements indicate whether the tooltip should appear directly
above, to the right of, beneath, or to the left of the button respectively. The -start and -end
suffixes shift the placement away from the centerline.
For example, the top placement is directly above the inside content and centered on it, but top-end
appears from the top right corner of the inside content for left-to-right languages like English.
Tooltip Distance (distance)
Use this setting to determine how many pixels away from the icon button the tooltip renders when active.
The default value in Shoelace is 8 pixels.
Tooltip Skidding (skidding)
Use this setting to determine how many pixels from the defined placement the tooltip renders along the
icon. This shifts the tooltip along the cross-axis from the distance setting.
The default value in Shoelace is 0 pixels.
Use Legacy Table of Contents Control (use_legacy)
Use this setting to choose whether to use the legacy implementation for the mobile menu control. The current
default value is true, which renders the old SVG icon and ignores all other settings for the control.
In the future, the default value will change to false. Later, this setting will be removed and only the
new implementation will be available. We strongly recommend you update this setting to false and adjust
your site’s theme as needed.