|
1 | 1 | # next-layout |
2 | | -Let your Next.js pages choose which layout to use, while keeping layouts persistent whenever possible |
| 2 | + |
| 3 | +[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][build-status-image]][build-status-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url] |
| 4 | + |
| 5 | +[npm-url]:https://npmjs.org/package/@moxy/next-layout |
| 6 | +[downloads-image]:https://img.shields.io/npm/dm/@moxy/next-layout.svg |
| 7 | +[npm-image]:https://img.shields.io/npm/v/@moxy/next-layout.svg |
| 8 | +[build-status-url]:https://github.com/moxystudio/next-layout/actions |
| 9 | +[build-status-image]:https://img.shields.io/github/workflow/status/moxystudio/next-layout/Node%20CI/master |
| 10 | +[codecov-url]:https://codecov.io/gh/moxystudio/next-layout |
| 11 | +[codecov-image]:https://img.shields.io/codecov/c/github/moxystudio/next-layout/master.svg |
| 12 | +[david-dm-url]:https://david-dm.org/moxystudio/next-layout |
| 13 | +[david-dm-image]:https://img.shields.io/david/moxystudio/next-layout.svg |
| 14 | +[david-dm-dev-url]:https://david-dm.org/moxystudio/next-layout?type=dev |
| 15 | +[david-dm-dev-image]:https://img.shields.io/david/dev/moxystudio/next-layout.svg |
| 16 | + |
| 17 | +Add persistent layouts to your Next.js projects in a declarative way. |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +```sh |
| 22 | +$ npm install @moxy/next-layout |
| 23 | +``` |
| 24 | + |
| 25 | +This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly. |
| 26 | + |
| 27 | +## Motivation |
| 28 | + |
| 29 | +Next.js projects usually have the need to have one or more layouts. Layouts are the "shell" of your app and usually contain navigation elements, such as an header and a footer. In the ideal scenario, each page would be able to say which layout they want to use, including tweaking its properties dynamically, such as `variant="light"`. However, we also want to keep the layout persistent in the React tree, to avoid having to remount it every time a user navigate between pages. |
| 30 | + |
| 31 | +Historically, projects overlook the need of multiple layouts or the ability to change layout props between pages. They start off with a simple layout and only later they handle this need, often with poor and non-scalable solutions. |
| 32 | + |
| 33 | +This library solves the need for multi-layouts and changing layout props dynamically in a consistent and reusable way. |
| 34 | + |
| 35 | +## Usage |
| 36 | + |
| 37 | +Setup `<LayoutManager>` in your `pages/_app.js` component: |
| 38 | + |
| 39 | +```js |
| 40 | +import React from 'react'; |
| 41 | +import { LayoutManager } from '@moxy/next-layout'; |
| 42 | + |
| 43 | +const App = ({ Component, pageProps }) => ( |
| 44 | + <LayoutManager |
| 45 | + Component={ Component } |
| 46 | + pageProps={ pageProps } /> |
| 47 | +); |
| 48 | + |
| 49 | +export default App; |
| 50 | +``` |
| 51 | + |
| 52 | +...and then use `withLayout` in your page components, e.g.: in `pages/about.js`: |
| 53 | + |
| 54 | +```js |
| 55 | +import React from 'react'; |
| 56 | +import { withLayout } from '@moxy/next-layout'; |
| 57 | +import { PrimaryLayout } from '../components'; |
| 58 | +import styles from './about.module.css'; |
| 59 | + |
| 60 | +const About = () => ( |
| 61 | + <div className={ styles.about }> |
| 62 | + <h1>About</h1> |
| 63 | + </div> |
| 64 | +); |
| 65 | + |
| 66 | +export default withLayout(<PrimaryLayout variant="light" />)(About); |
| 67 | +``` |
| 68 | + |
| 69 | +ℹ️ Layouts will receive the page to be rendered as the `children` prop. |
| 70 | + |
| 71 | +## API |
| 72 | + |
| 73 | +`@moxy/next-layout` exposes a `<LayoutManager>` component and a `withLayout` to be used in pages. |
| 74 | + |
| 75 | +### <LayoutManager> |
| 76 | + |
| 77 | +A component that manages the current layout to be used based on what the active page specifies. It keeps the layout persistent between page transitions whenever possible (e.g.: when the layout is the same). |
| 78 | + |
| 79 | +Here's the list of props it supports: |
| 80 | + |
| 81 | +#### Component |
| 82 | + |
| 83 | +Type: `ReactElementType` |
| 84 | + |
| 85 | +The page component, which maps to your App `Component` prop. |
| 86 | + |
| 87 | +#### pageProps |
| 88 | + |
| 89 | +Type: `object` |
| 90 | + |
| 91 | +The page component props, which maps to your App `pageProps` prop. |
| 92 | + |
| 93 | +#### defaultLayout |
| 94 | + |
| 95 | +Type: `ReactElement` |
| 96 | + |
| 97 | +The default layout to be used when a child page doesn't explicitly sets one. |
| 98 | + |
| 99 | +```js |
| 100 | +// pages/_app.js |
| 101 | +import React from 'react'; |
| 102 | +import { LayoutManager } from '@moxy/next-layout'; |
| 103 | +import { PrimaryLayout } from '../components'; |
| 104 | + |
| 105 | +const App = ({ Component, pageProps }) => ( |
| 106 | + <LayoutManager |
| 107 | + Component={ Component } |
| 108 | + pageProps={ pageProps } |
| 109 | + defaultLayout={ <PrimaryLayout /> } /> |
| 110 | +); |
| 111 | + |
| 112 | +export default App; |
| 113 | +``` |
| 114 | + |
| 115 | +#### children |
| 116 | + |
| 117 | +Type: `function` |
| 118 | + |
| 119 | +A [render prop](https://reactjs.org/docs/render-props.html) to override the default render behavior. |
| 120 | + |
| 121 | +Its signature is `({ Layout, layoutProps, layoutKey, Component, pageProps, pageKey }) => <ReactElement>`, where: |
| 122 | + |
| 123 | +- `Layout` is the layout React component that should be rendered |
| 124 | +- `layoutProps` is the props that should be passed to the layout React component |
| 125 | +- `layoutKey` is a unique string for the layout to be used as `key` |
| 126 | +- `Component` is the page React component that should be rendered |
| 127 | +- `pageProps` is the props that should be passed to the page React component, and already includes `setLayoutProps` if the page was wrapped with [`withLayout`](#withlayoutlayoutpage) |
| 128 | +- `pageKey` is a unique string for the page to be used as `key` |
| 129 | + |
| 130 | +Passing a custom `children` render prop is useful to add layout and page transitions. Here's an example that uses [`react-transition-group`](https://reactcommunity.org/react-transition-group/) to apply a simple fade transition between layouts and pages: |
| 131 | + |
| 132 | +```js |
| 133 | +// pages/_app.js |
| 134 | +import React from 'react'; |
| 135 | +import { LayoutManager } from '@moxy/next-layout'; |
| 136 | +import { TransitionGroup, CSSTransition } from 'react-transition-group'; |
| 137 | +import { PrimaryLayout } from '../components'; |
| 138 | + |
| 139 | +const App = ({ Component, pageProps }) => ( |
| 140 | + <LayoutManager |
| 141 | + Component={ Component } |
| 142 | + pageProps={ pageProps } |
| 143 | + defaultLayout={ <PrimaryLayout /> }> |
| 144 | + { ({ Layout, layoutProps, layoutKey, Component, pageProps, pageKey }) => ( |
| 145 | + <TransitionGroup> |
| 146 | + <CSSTransition key={ layoutKey } classNames="fade"> |
| 147 | + <Layout { ...layoutProps }> |
| 148 | + <TransitionGroup> |
| 149 | + <CSSTransition key={ pageKey } classNames="fade"> |
| 150 | + <Component { ...pageProps } /> |
| 151 | + </CSSTransition> |
| 152 | + </TransitionGroup> |
| 153 | + </Layout> |
| 154 | + </CSSTransition> |
| 155 | + </TransitionGroup> |
| 156 | + ) } |
| 157 | + </LayoutManager> |
| 158 | +); |
| 159 | +``` |
| 160 | + |
| 161 | +### withLayout(layout?)(Page) |
| 162 | + |
| 163 | +Sets up a `Page` component with the ability to select which `layout` to use. Moreover, it injects a `setLayoutProps` prop so that you may dynamically update the layout props. |
| 164 | + |
| 165 | +#### layout |
| 166 | + |
| 167 | +Type: `ReactElement` or `function` |
| 168 | + |
| 169 | +The layout to use for the `Page`. Can either be a `ReactElement` or a function that returns it. |
| 170 | + |
| 171 | +The function form is useful when page props affects layout props. It has the following signature: `(ownProps) => <ReactElement>`. Please note that the function only runs once to determine the layout and its initial props. |
| 172 | + |
| 173 | +#### Page |
| 174 | + |
| 175 | +Type: `ReactElementType` |
| 176 | + |
| 177 | +The page component to wrap. |
| 178 | + |
| 179 | +#### Injected setLayoutProps |
| 180 | + |
| 181 | +Type: `function` |
| 182 | + |
| 183 | +Allows to dynamically change the layout props. Has the following signature: `(updater | stateChange, callback?)`. |
| 184 | + |
| 185 | +The behavior of `setLayoutProps` is exactly the same as [`setState`](https://reactjs.org/docs/react-component.html#setstate) of class components, supporting both an object or an updater function. |
| 186 | + |
| 187 | +```js |
| 188 | +// pages/about.js |
| 189 | +import React, { useCallback } from 'react'; |
| 190 | +import { withLayout } from '@moxy/next-layout'; |
| 191 | +import { PrimaryLayout } from '../components'; |
| 192 | + |
| 193 | +import styles from './about.module.css'; |
| 194 | + |
| 195 | +const About = ({ setLayoutProps }) => { |
| 196 | + const handleSetToDark = useCallback(() => { |
| 197 | + setLayoutProps({ variant="dark" }); |
| 198 | + // ..or setLayoutProps((layoutProps) => ({ variant="dark" })); |
| 199 | + }, [setLayoutProps]); |
| 200 | + |
| 201 | + return ( |
| 202 | + <div className={ styles.about }> |
| 203 | + <h1>About</h1> |
| 204 | + <button onClick={ handleSetToDark }>Enable dark mode</button> |
| 205 | + </div> |
| 206 | + ); |
| 207 | +}; |
| 208 | + |
| 209 | +export default withLayout(<PrimaryLayout variant="light" />)(About); |
| 210 | +``` |
| 211 | + |
| 212 | +## Tests |
| 213 | + |
| 214 | +```sh |
| 215 | +$ npm test |
| 216 | +$ npm test -- --watch # during development |
| 217 | +``` |
| 218 | + |
| 219 | +## License |
| 220 | + |
| 221 | +Released under the [MIT License](https://www.opensource.org/licenses/mit-license.php). |
0 commit comments