preact-layout

Small and simple layout library for Preact.

Think out of the box!

Preact is beautiful and pure. Literally, because with Preact we mostly write pure components that take properties and render markup possibly including child components that we control via their props. Information flows one way and everything is good.

But what if a component needs to render some data in another section of the page? In the header for example? Do we really have to make the root component aware of the title of each page? What if we need something in the footer as well? Or in some sidebar? We want our components to be able to contribute content to other sections of the page, even if those sections are higher up the tree... Is it even possible?

preact-layout does not only make this possible, it makes it simple!

Getting Started

Getting started with preact-layout:

Play with the Preact Layout Kickstart CodePen.
Setup - Add preact-layout to your project
Basic Usage - Using Layout, Section and contribution functions
Examples - Learn by example!

Why

Preact Layout elegantly solves some common layout challenges you will undoubtedly encounter when using Preact, due to the hierarchical nature of the component tree and the one-way data flow. Preact Layout allows you to think out of the box.

Simple but powerful API

With just 2 components, the API is very simple to learn, yet powerful.

Layout to define layouts
Section to divide the layout into multiple sections

Lightweight

preact-layout is microscopically small. The sources are just over 2 Kb and the minified and gzipped distribution file weighs only 1 kB.

Well documented

A good library needs plenty of good docs. In the case of preact-layout, the docs are way bigger than the library itself! We have a Usage guide, API docs, Examples and a Preact Layout Kickstart CodePen to learn from.

Well tested

Good tests ensure not only that the code works, but that it keeps working! We use Travis CI to test every push to master so we catch any bugs before they make it into a release.

Open Source, Open Community

preact-layout is Open Source software with a public code repository and public issue tracker.

Using preact-layout

Define contribution functions
Create a layout
Use the contribution functions in your components
Nest the component inside the layout

Define contribution functions

preact-layout allows you to define contribution functions that are used as JSX tags that signal that the components contained in those tags should be contributed to another section of the parent layout.

For example, for a simple layout with a header and a footer around some main content block, we might define these functions:

function Header(){}
function Footer(){}

Create a layout

Create a layout with sections for the Header and Footer:

function MyLayout({children}) {return (
    <Layout>
        <div>
            <header>
                <Section type={Header}><b>header</b></Section>
            </header>

            <Section>{children}</Section>

            <footer>
                <Section type={Footer}><i>footer</i></Section>
            </footer>
        </div>
    </Layout>
)}

Use the contribution functions in your components

Now, we can build components that use the contribution functions to contribute components to the related sections of the layout:

function MyPage(){return (
    <div>
        <Header><h1>my page</h1></Header>
        <article>main article</article>
        <Footer>goodbye</Footer>
    </div>
)}

Nest the component inside the layout

Finally, render the component nested within the layout:

render(
    <MyLayout>
        <MyPage />
    </MyLayout>
    ,
    document.getElementsByTagName('body')[0]
)

This will result in:

<div>
    <header>
        <h1>my page</h1>
    </header>
    <div>
        <article>main article</article>
    </div>
    <footer>
        goodbye
    </footer>
</div>

Component Reference

Layout - Create layouts using Layout
Section - Divide your layout into named Sections
contribution functions - Defining conribution functions

Performance considerations

When collecting contributions, preact-layout peeks ahead at the elements that the child components will produce by rendering those child components. The resulting elements could itself again contain components, which would need to be rendered as well, leading to recursive rendering that of course comes at a performance cost. You can tune this cost by setting the recurse attribute on the Layout to some positive number. It defaults to 9.

Issues

Add an issue in this project's issue tracker to let me know of any problems you find, or questions you may have.

Contributing

This project welcomes contributions from the community! Learn more in the contributing guide.

Copyright

License

Licensed under the Creative Commons Attribution 4.0 International (CC-BY-4.0) Open Source license.

Introduction