preact-habitat
v3.3.0
Published
A place for your happy widget in every DOM.
Downloads
3,432
Maintainers
Readme
Preact Habitat
A 900 Bytes module for that will make plugging in Preact components and widgets in any CMS or website as fun as lego!
Demos
Login Widget Source Code 💻
Login Widget Integration pen Codepen Demo 🖋
Installation
npm install --save preact-habitat
Core Features
- 2 ways to passing props from DOM.
- Multiple rendering options.
- Light weight ( < 1KB ).
- Compatible with React widgets through preact-compat.
- In use in high traffic web applications.
Basic Usage Example
import habitat from 'preact-habitat';
import WidgetAwesome from './components/WidgetAwesome';
const { render } = habitat(WidgetAwesome);
/**
** other selecors options:
**
** ".classname" for querying DOM element by its class name
**
** "#div-id" for querying DOM element by its ID value
**
** "[data-attribute-example='widget-here']" for querying DOM element by its data attribute name & val
**
**/
render({
selector: '.some-class', // Searches and mounts in <div class="some-class"></div>
defaultProps: undefined, // Default props for all widgets
inline: false,
clean: false,
clientSpecified: false
});
in webpack.config.js
or any other build tool bundle output format should be UMD
:
output: {
libraryTarget: 'umd'
}
in the DOM you'd like to mount your widget in:
<div class="some-class"> <!-- as specified in render, habitat will mount the component in this-->
<script type="application/json">
{
"title": "Widget Title passed as prop",
"theme": "red",
"anotherProp": "Thanks for trying this widget out!"
}
</script>
</div>
Now, build your production ready preact widget and you're all set, TADA! 🎉
API Docs
habitat(...)
accepts a single Preact component as its only argument
example:
import { h } form 'preact';
import habitat from 'preact-habitat';
const Widget = () => <h1>Hello, World!</h1>;
const { render } = habitat(Widget); // NOTE: pass Widget and not <Widget />
render({
...
});
render(options)
render function accepts an options Object which supports the following properties:
option.selector
String:
.myclass
,#myid
,[data-selector="my-data-attr"]
DOM Element selector used to retrieve the DOM elements you want to mount the widget in
option.defaultProps
Object: {} || undefined (default)
Default props to be rendered throughout widgets, you can replace each value declaring props.
option.inline
Boolean: true || false (default)
Set to true if you want to use the parent DOM node as a host for your widget without specifing any selectors.
example:
<div class="beautiful-container">
<!-- inline set to true will make this widget render in it's parent
wrapper class="beautiful-container" without using selector option-->
<script async src="cdn.preactwidget..."></script>
</div>
option.clean
Boolean: true || false (default)
clean will remove all the innerHTML from the HTMl element the widget will mount in.
example:
if we set the widget to be mounted inside the selector ".beautiful-container" with {clean: true} it will remove the Loading div as soon as it renders.
<div class="beautiful-container">
<div class="loader">LOADING...</div>
</div>
<script async src="cdn.preactwidget..."></script>
option.clientSpecified
Boolean: true || false (default)
This option allows who ever using the script to specifit the selector which they'd like to mount the widget in
<div class="beautiful-container">
<div class="loader">LOADING...</div>
</div>
<script async src="cdn.preactwidget..." data-mount-in=".beautiful-container"></script>
Passing Props
There are 2 ways to pass props, either via data-attributes or application/json script tag
via props script
Simply add a <script>
tag with type="application/json"
or type="text/props"
and ensure the content is valid JSON. multiple script tags will be merged together and passed down.
<div class="beautiful-container" data-prop-name="preact habitat" data-prop-version="v3.0.0" data-prop-theme-color="green">
<script type="application/json">
{
"name": "preact habitat",
"version":"v3.0.0",
"themeColor": "green"
}
</script>
</div>
via data-attribute
the data attribute has to always start with data-prop-
examples:
data-prop-name
will be available in your component as name
data-prop-version
will be available in your component as version
data-prop-theme-color
will be available in your component as themeColor
NOTE the lowerCamelCase when there's a -
<div class="beautiful-container" data-prop-name="preact habitat" data-prop-version="v3.0.0" data-prop-theme-color="green">
</div>
License
MIT - Copyright (c) Zouhir Chahoud
Credits
Artwork By: Oleg Turbaba, Dribble