https://github.com/prantlf/holy-grail-layout
Provides an extended "Holy Grail" layout as a web component.
https://github.com/prantlf/holy-grail-layout
custom-element element holy-grail holy-grail-layout holygrail holygrail-layout html html-element layout web-component webcomponent
Last synced: 4 months ago
JSON representation
Provides an extended "Holy Grail" layout as a web component.
- Host: GitHub
- URL: https://github.com/prantlf/holy-grail-layout
- Owner: prantlf
- License: mit
- Created: 2023-03-27T01:05:25.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-07-10T23:10:53.000Z (about 2 years ago)
- Last Synced: 2025-02-19T13:48:19.754Z (over 1 year ago)
- Topics: custom-element, element, holy-grail, holy-grail-layout, holygrail, holygrail-layout, html, html-element, layout, web-component, webcomponent
- Language: HTML
- Homepage:
- Size: 407 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Holy-Grail Layout
[](https://www.npmjs.com/package/holy-grail-layout#top)
[](https://www.webcomponents.org/element/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](#intellisense) for VS Code
## Synopsis
```html
...
...
...
...
...
...
...
```
## 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-layout
```
If you write a plain HTML page, insert the `holy-grail-layout` script pointing either to CDN or to the local filesystem:
```html
```
## 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.
```html
...
```
#### 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%`.
```css
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:
```css
holy-grail::part(side-start) {
width: 33%;
}
```
#### Examples
All slots populated, screen wider than 767px, see [the source](example/complete.html):
```html
...
...
...
...
...
...
...
```
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](example/partial.html):
```html
...
...
...
...
...
```
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`:
```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.
[web component]: https://developer.mozilla.org/en-US/docs/Web/Web_Components
[Custom Element Manifest]: https://github.com/webcomponents/custom-elements-manifest#readme
[Web Worker]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API
[Node.js]: https://nodejs.org/
[NPM]: https://docs.npmjs.com/cli/npm
[Yarn]: https://classic.yarnpkg.com/docs/cli/
[PNPM]: https://pnpm.js.org/pnpm-cli