holy-grail-layout v2.1.1
Holy-Grail Layout
Provides an extended "Holy Grail" layout as a web component.
Features:
- Lightweight (graph 2.88 kB minified, 1.34 kB gzipped, 1.14 kB brotlied)
- Custom Element Manifest
- IntelliSense for VS Code
Synopsis
<holy-grail>
<header slot="head">...</header>
<nav slot="nav-top">...</nav>
<main slot="main">...</main>
<nav slot="nav-bottom">...</nav>
<aside slot="side-start">...</aside>
<aside slot="side-end">...</aside>
<footer slot="foot">...</footer>
</holy-grail>
<script defer src=https://unpkg.com/holy-grail-layout@2.0.0/dist/index.min.js></script>
Installation
Make sure that you have installed Node.js. Use your favourite package manager (NPM, Yarn or PNPM) to add the holy-grail-layout module to your project. Add -D on the command line if you use a bundler:
npm i holy-grail-layout
yarn add holy-grail-layout
pnpm i holy-grail-layoutIf you write a plain HTML page, insert the holy-grail-layout script pointing either to CDN or to the local filesystem:
<script src=https://unpkg.com/holy-grail-layout@2.0.0/dist/index.min.js></script>
<script src=node_modules/holy-grail-layout/dist/index.min.js></script>Elements
holy-grail
The custom element holy-grail renders a "Holy Grail" layout in its shadow root and populates its parts from teh corresponding slots.
<holy-grail>...</holy-grail>Attributes
| Name | Type | Description |
|---|---|---|
| size | string | Disables the responsive behaviour by forcing the screen width to be detected as small, medium or large. |
The width breakpoint between small and medium sizes is 480px. The width breakpoint between medium and large sizes is 768px.
Slots
| Name | Description |
|---|---|
| head | Topmost horizontal slot, as wide as the whole element, as high as its content. |
| nav-top | A horizontal slot above the "main" slot, as wide as the "main" slot, as high as its content. |
| main | A large slot in the middle of the element, fills the rest of width and height of the element. |
| nav-bottom | A horizontal slot below the "main" slot, as wide as the "main" slot, as high as its content. |
| side-start | A vertical slot on the left side(in the left-to-right text-writing direction) with an explicit width (25% of the element by default), as high as the content between the \"head\" and \"foot\" slots. The width can be customised by a style using the part \"side-start\" in the selector. |
| side-end | A vertical slot on the right side (in the left-to-right text-writing direction) with an explicit width (25% of the element by default), as high as the content between the \"head\" and \"foot\" slots. The width can be customised by a style using the part \"side-end\" in the selector. |
| foot | Bottommost horizontal slot, as wide as the whole element, as high as its content. |
Styles
CSS variables --holy-grail-side-start-width and --holy-grail-side-end-width can be used to set the widths of the slots side-start and side-end. The default values are 25%.
holy-grail {
--holy-grail-side-start-width: 33%;
}Parts main, side-start and side-end can be used for advanced styling of the stretchable slots of the layout:
holy-grail::part(side-start) {
width: 33%;
}Examples
All slots populated, screen wider than 767px, see the source:
<holy-grail>
<header slot="head">...</header>
<nav slot="nav-top">...</nav>
<main slot="main">...</main>
<nav slot="nav-bottom">...</nav>
<aside slot="side-start">...</aside>
<aside slot="side-end">...</aside>
<footer slot="foot">...</footer>
</holy-grail>
All slots populated, screen wider than 479px, but narrower than 768px:
All slots populated, screen narrower than 480px:
Only some slots populated, screen wider than 767px, see the source:
<holy-grail>
<header slot="head">...</header>
<nav slot="nav-top">...</nav>
<main slot="main">...</main>
<nav slot="nav-bottom">...</nav>
<aside slot="side-start">...</aside>
</holy-grail>
Only some slots populated, screen wider than 479px, but narrower than 768px:
Only some slots populated, screen narrower than 480px:
IntelliSense
The language support in the VS Code editor can offer auto-completion and hover information for custom elements. To enable this feature for custom elements in this package, insert the following property to settings.json:
"html.customData": ["node_modules/holy-grail-layout/dist/html-custom-data.json"]You will need to restart the VS Code to have this change applied.
License
Copyright (c) 2023 Ferdinand Prantl
Licensed under the MIT license.