macro-components
Create flexible layout and composite UI components without the need to define arbitrary custom props.
npm i macro-components
import React from 'react'import styled from 'styled-components'import Macro from 'macro-components'import space fontSize color from 'styled-system' // Define some styled-componentsconst Box = styleddiv` `BoxdisplayName = 'Box' const Image = styledimg` max-width: 100%; height: auto; `ImagedisplayName = 'Image' const Heading = styledh2` `HeadingdisplayName = 'Heading' const Text = styleddiv` `TextdisplayName = 'Text' // create a macro function with the UI components you intend to useconst macro = // Create a macro-componentconst MediaObject =
import MediaObject from './MediaObject' // get the macro component's child componentsconst Image Heading Text = MediaObject // Use the macro-component by passing the components as childrenconst App = <div> <MediaObject> <Image ='kitten.png' /> <Heading> Hello </Heading> <Text> This component keeps its tree structure but still allows for regular composition </Text> </MediaObject> </div>
Features
- Single component creator
- Intended for use with libraries like styled-components & glamorous
- Encapsulate layout structure in composable components
- Help keep your component API surface area to a minimum
- Works with any other React components
Note: Macro components are intended to only work with specific child components. If you're wanting to define slots, see the Alternatives section below.
Motivation
Often it's best to use React composition and props.children
to create UI that is composed of multiple elements,
but sometimes you might want to create larger composite components
with encapsulated tree structures for layout
or create Bootstrap-like UI components
such as panels, cards, or alerts.
This library lets you create composite components
with encapsulated DOM structures
without the need to define arbitrary props APIs
and that work just like any other React composition.
This can help ensure that your component API surface area remains small and easier to maintain.
If you find yourself creating composite React components that don't map to data structures, as described in Thinking in React, then this module is intended for you.
Usage
Macro(componentsObject)(elementFunction)
Returns a React component with a composable API that keeps tree layout structure.
const Banner = // the element function receives child elements // named according to the components object Heading Subhead <Box = ='white' ='blue'> Heading Subhead </Box>
The elementFunction
argument is called with an object of elements
based on the componentsObject
passed to the Macro function.
Using the Banner component above would look something like the following.
import Banner from './Banner' const App = <Banner> <Banner.Heading>Hello</Banner.Heading> <Banner.Subhead>Subhead</Banner.Subhead> </Banner>
componentsObject
The components object is used to defined which components the macro component will accept as children.
elementFunction
The element function is similar to a React component, but receives an elements object as its first argument and props as its second one. The elements object is created from its children and is intended to make encapsulating composition and element structures easier.
Within the macro component, the element function is called with the elements object and props: elementFunction(elementsObject, props)
.
// exampleconst elFunc = Heading Text props <header> Heading Text </header> const Heading = styledh2``const Text = styleddiv`` const componentsObj = Heading Text const SectionHeader = elFunc
Omitting children
For any element not passed as a child to the macro component,
the element function will render undefined
and React will not render that element.
This is useful for conditionally omitting optional children
const macro = const Message = <Flex = ='lightYellow'> Icon Text <Box ='auto' /> CloseButton </Flex>
import Message from './Message' const Text CloseButton = Message // Omitting the Icon child element will render Message without an icon.const message = <Message> <Text>propsmessage</Text> <CloseButton = /> </Message>
Props passed to the root component
The second argument passed to the element function allows you to pass props to the root element or any other element within the component.
const macro = const Card =
// example usage<Card ='tomato'> <Card.Image ='kittens.png' /> <Card.Text>Meow</Card.Text></Card>
Clone Component
To apply default props to the elements passed in as children, use the Clone component in an element function.
import Macro Clone from 'macro-components'import Heading Text from './ui' const macro = const Header =
Using a Component Multiple Times
To use the same component twice, give it a unique key in the componentsObject.
import React from 'react'import Macro from 'macro-components'import Heading from './ui' const macro = const Header =
<Header> <Header.Heading>Hello</Header.Heading> <Header.Subhead>Subhead</Header.Subhead></Header>
Alternatives
To create layout components that are not coupled to specific child components, using props or ordered children is probably a simpler approach.
The solutions below allow you to pass any arbitrary components as props or children.
See this discussion for more.
// using custom propsconst MyLayout = left right <Flex> <Box => left </Box> <Box => right </Box> </Flex> <MyLayout = =/>
// using ordered childrenconst Header = { const first second = ReactChildren return <Box => first second </Box> } <Header> <Heading>First</Heading> <Text>Second</Text></Header>
// using a children objectconst Header = children: left right <Flex> <Box> left </Box> <Box => right </Box> </Flex> <Header> left: <Image ='kitten.png' /> right: <Text>Meow</Text> </Header>
Related
- styled-components
- glamorous
- emotion
- styled-system
- system-components
- MediaObject example based on: The media object saves hundreds of lines of code