This PostHTML plugin provides an HTML-friendly syntax for using components in your HTML templates.
If you are familiar with Blade, React, Vue or similar, you will find the syntax to be familiar, as this plugin is inspired by them.
You might have noticed that the src/button.html component contains type and class attributes, and that we also passed those attributes when we used it in src/index.html.
The result is that type was overridden, and class was merged.
By default, class and style attributes are merged, while all others attribute are overridden. You can also override class and style attributes by prepending override: to the class attribute.
All attributes that you pass to the component will be added to the first node of your component or to the node with an attribute named attributes, only if they are not defined as props via <script props> or if they are not "known attributes" (see
valid-attributes.js).
You can also define which attributes are considered to be valid, via the plugin's options.
The <yield> tag is where content that you pass to a component will be injected.
The plugin configures the PostHTML parser to recognize self-closing tags, so you can also just write is as <yield />.
For brevity, we will use self-closing tags in the examples.
fileExtension
By default, the plugin looks for components with the .html extension. You can change this by passing an array of extensions to the fileExtension option.
When using an array, if two files with the same name match both extensions, the file matching the first extension in the array will be used.
If your components are in a sub-folder with multiple files, then in order to avoid writing out the main file name you can use index.html without specifying it.
Here's an example:
<!-- src/components/modals/index.html --><x-modal.index>Submit</x-modal.index><!-- You may omit "index" part since the file is named "index.html" --><x-modal>Submit</x-modal>
Parser options
You may pass options to posthtml-parser via options.parserOptions.
[!IMPORTANT]
The parserOptions that you pass to the plugin must also be passed in the process method in your code, otherwise your PostHTML build will use posthtml-parser defaults and will override anything you've passed to posthtml-component.
Self-closing tags
The plugin supports self-closing tags by default, but you need to make sure to enable them in the process method in your code too, by passing recognizeSelfClosing: true in the options object:
If you don't add this to process, PostHTML will use posthtml-parser defaults and will not support self-closing component tags. This will result in everything after a self-closing tag not being output.
Multiple folders
You have full control over where your component files exist. Once you set the base root path of your components, you can then set multiple folders.
For example if your root is ./src and then you have several folders where you have your components, for example ./src/components and ./src/layouts, you can set up the plugin like below:
With namespaces, you can define a top level root path to your components.
It can be useful for handling custom themes, where you define a specific top level root with a fallback root for when a component is not found, and a custom root for overriding.
This makes it possible to create folder structures like this:
src (root folder)
components (folder for components like modal, button, etc.)
layouts (folder for layout components like base layout, header, footer, etc.)
theme-dark (namespace folder for theme-dark)
components (folder for components for theme dark)
layouts (folder for layout components for dark theme)
theme-light (namespace folder for theme-light)
components (folder for components for light theme)
layouts (folder for layout components for dark theme)
custom (custom folder for override your namespace themes)
theme-dark (custom folder for override dark theme)
components (folder for override components of theme dark)
layouts (folder for override layout components of dark theme)
theme-light (custom folder for override light theme)
components (folder for override components of theme dark)
layouts (folder for override layout components of dark theme)
And the options would be like:
// index.jsconst options = { // Root for component without namespace root: './src', // Folders is always appended in 'root' or any defined namespace's folders (base, fallback or custom) folders: ['components', 'layouts'], namespaces: [{ // Namespace name will be prepended to tag name (example <x-theme-dark::button>) name: 'theme-dark', // Root of the namespace root: './src/theme-dark', // Fallback root when a component is not found in namespace fallback: './src', // Custom root for overriding, the lookup happens here first custom: './src/custom/theme-dark' }, { // Light theme name: 'theme-light', root: './src/theme-light', fallback: './src', custom: './src/custom/theme-light' }, { /* ... */ }]};
You may push content to named stacks which can be rendered somewhere else, like in another component. This can be particularly useful for specifying any JavaScript or CSS required by your components.
The once attribute allows you to push content only once per rendering cycle.
For example, if you are rendering a given component within a loop, you may wish to only push the JavaScript and CSS the first time the component is rendered.
Example.
<!-- src/modal.html --><div class="modal"> <!-- ... --></div><!-- The push content will be pushed only once in the stack --><push name="styles" once> <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet"></push><push name="scripts" once> <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js"></script></push>
By default, the content is pushed in the stack in the given order. If you would like to prepend content onto the beginning of a stack, you may use the prepend attribute:
<push name="scripts"> <!-- This will be second --> <script src="/example.js"></script></push><!-- Later... --><push name="scripts" prepend> <!-- This will be first --> <script src="/example-2.js"></script></push>
Props
props can be passed to components in HTML attributes. To use them in a component, they must be defined in the component's <script props> tag.
<div> Prop in parent: My title <div> Prop in child: Default title </div></div>
As you can see, title in <x-child> component renders the default value and not the one set via <x-parent>.
To change this, we must prepend aware: to the attribute name in order to pass the props to nested components.
<x-parent aware:title="My title" />
The output now will be:
<div> Prop in parent: My title <div> Prop in child: My title </div></div>
Attributes
You can pass any attributes to your components and they will be added to the first node of your component,
or to the node with an attribute named attributes.
You can add custom rules to define how attributes are parsed - we use posthtml-attrs-parser to handle them.
Plugins
Use the plugins option to apply your own PostHTML plugins to the components.
This can be an array of plugins, or an object with before and after properties to apply plugins before or after the posthtml-expressions plugin runs.
// As arrayconst options = { plugins: [/* ... */]};// As object with `before` and `after`const options = { plugins: { before: [/* ... */], after: [/* ... */], } };
When using plugins as an array, the plugins will be applied after posthtml-expressions.
Advanced attributes configurations
If default configurations for valid attributes are not right for you, you may configure them as explained below.
// index.jsconst { readFileSync, writeFileSync } = require('fs')const posthtml = require('posthtml')const components = require('posthtml-component')const options = { root: './src', // Add attributes to specific tag or override defaults elementAttributes: { DIV: (defaultAttributes) => { /* Add new one */ defaultAttributes.push('custom-attribute-name'); return defaultAttributes; }, DIV: (defaultAttributes) => { /* Override all */ defaultAttributes = ['custom-attribute-name', 'another-one']; return defaultAttributes; }, }, // Add attributes to all tags, use '*' as wildcard for attribute name that starts with safelistAttributes: [ 'custom-attribute-name', 'attribute-name-start-with-*' ], // Remove attributes from all tags that support it blocklistAttributes: [ 'role' ]}posthtml(components(options)) .process(readFileSync('src/index.html', 'utf8')) .then(result => writeFileSync('dist/index.html', result.html, 'utf8'))
Examples
You can work with <slot> and <fill> or you can create component for each block of your component, and you can also support both of them.
You can find an example of this inside docs-src/components/modal. Following is a short explanation of both approaches.
Using slots
Let's suppose we want to create a component for bootstrap modal.
Now you can use your component with slots or with small components.
As you may notice, by using slots, you already can use also your small components, and so you can also pass props
via $slots which has all the props passed via slot, and as well check if slot is filled.
Migration
If you are migrating from posthtml-extend and/or posthtml-modules please to follow updates here:
posthtml-components/issues/16.
Thanks to all PostHTML contributors and especially to posthtml-extend and posthtml-modules contributors, as part of code is stolen inspired from these plugins.
Huge thanks also to Laravel Blade template engine.