{"id":13394391,"url":"https://github.com/jxnblk/macro-components","last_synced_at":"2025-08-29T05:06:11.362Z","repository":{"id":40003168,"uuid":"109044877","full_name":"jxnblk/macro-components","owner":"jxnblk","description":"Create flexible layout and composite UI components without the need to define arbitrary custom props","archived":false,"fork":false,"pushed_at":"2018-02-04T18:06:04.000Z","size":60,"stargazers_count":483,"open_issues_count":3,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-19T15:07:54.801Z","etag":null,"topics":["components","composite-components","react","style","styled-components","ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jxnblk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-31T19:46:15.000Z","updated_at":"2025-03-27T21:36:59.000Z","dependencies_parsed_at":"2022-06-26T07:31:04.881Z","dependency_job_id":null,"html_url":"https://github.com/jxnblk/macro-components","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jxnblk/macro-components","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmacro-components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmacro-components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmacro-components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmacro-components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jxnblk","download_url":"https://codeload.github.com/jxnblk/macro-components/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmacro-components/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272631632,"owners_count":24967104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["components","composite-components","react","style","styled-components","ui"],"created_at":"2024-07-30T17:01:17.899Z","updated_at":"2025-08-29T05:06:11.337Z","avatar_url":"https://github.com/jxnblk.png","language":"JavaScript","readme":"\n# macro-components\n\nCreate flexible layout and composite UI components without the need to define arbitrary custom props.\n\n\n[![Build Status][build-badge]][build]\n\u003c!-- cant log in so nope\n[![Coverage][coverage-badge]][coverage]\n--\u003e\n\n[build-badge]: https://img.shields.io/travis/jxnblk/macro-components/master.svg?style=flat-square\n[build]: https://travis-ci.org/jxnblk/macro-components\n[coverage-badge]: https://img.shields.io/codecov/c/github/jxnblk/macro-components.svg?style=flat-square\n[coverage]: https://codecov.io/github/jxnblk/macro-components\n\n```\nnpm i macro-components\n```\n\n```jsx\nimport React from 'react'\nimport styled from 'styled-components'\nimport Macro from 'macro-components'\nimport { space, fontSize, color } from 'styled-system'\n\n// Define some styled-components\nconst Box = styled.div`${space} ${fontSize} ${color}`\nBox.displayName = 'Box'\n\nconst Image = styled.img`\n  max-width: 100%;\n  height: auto;\n  ${space}\n`\nImage.displayName = 'Image'\n\nconst Heading = styled.h2`${space} ${fontSize} ${color}`\nHeading.displayName = 'Heading'\n\nconst Text = styled.div`${space} ${fontSize} ${color}`\nText.displayName = 'Text'\n\n// create a macro function with the UI components you intend to use\nconst macro = Macro({\n  Image,\n  Heading,\n  Text\n})\n\n// Create a macro-component\nconst MediaObject = macro(({\n  Image,\n  Heading,\n  Text\n}) =\u003e (\n  \u003cFlex p={2} align='center'\u003e\n    \u003cBox width={128}\u003e\n      {Image}\n    \u003c/Box\u003e\n    \u003cBox\u003e\n      {Heading}\n      {Text}\n    \u003c/Box\u003e\n  \u003c/Flex\u003e\n))\n```\n\n```jsx\nimport MediaObject from './MediaObject'\n\n// get the macro component's child components\nconst { Image, Heading, Text } = MediaObject\n\n// Use the macro-component by passing the components as children\nconst App = props =\u003e (\n  \u003cdiv\u003e\n    \u003cMediaObject\u003e\n      \u003cImage src='kitten.png' /\u003e\n      \u003cHeading\u003e\n        Hello\n      \u003c/Heading\u003e\n      \u003cText\u003e\n        This component keeps its tree structure but still allows for regular composition.\n      \u003c/Text\u003e\n    \u003c/MediaObject\u003e\n  \u003c/div\u003e\n)\n```\n\n## Features\n\n- Single component creator\n- Intended for use with libraries like [styled-components][sc] \u0026 [glamorous][glamorous]\n- Encapsulate layout structure in composable components\n- Help keep your component API surface area to a minimum\n- Works with *any* other React components\n\n**Note:** Macro components are intended to *only* work with specific child components. If you're wanting to define *slots*, see the [Alternatives](#alternatives) section below.\n\n## Motivation\n\nOften it's best to use [React composition][composition] and `props.children`\nto create UI that is composed of multiple elements,\nbut sometimes you might want to create larger composite components\nwith encapsulated tree structures for layout\nor create [Bootstrap][bootstrap]-like UI components\nsuch as panels, cards, or alerts.\nThis library lets you create composite components\nwith encapsulated DOM structures\nwithout the need to define arbitrary props APIs\nand that work just like any other React composition.\n\nThis can help ensure that your component API surface area remains small\nand easier to maintain.\n\nIf you find yourself creating composite React components that don't map to data structures,\nas described in [Thinking in React][thinking-in-react],\nthen this module is intended for you.\n\n[composition]: https://reactjs.org/docs/composition-vs-inheritance.html\n[thinking-in-react]: https://reactjs.org/docs/thinking-in-react.html\n[bootstrap]: https://getbootstrap.com\n\n## Usage\n\n`Macro(componentsObject)(elementFunction)`\n\nReturns a React component with a composable API that keeps tree layout structure.\n\n```jsx\nconst Banner = Macro({\n  // pass a components object\n  Heading,\n  Subhead\n})(({\n  // the element function receives child elements\n  // named according to the components object\n  Heading,\n  Subhead\n}) =\u003e (\n  \u003cBox p={3} color='white' bg='blue'\u003e\n    {Heading}\n    {Subhead}\n  \u003c/Box\u003e\n)\n```\n\nThe `elementFunction` argument is called with an object of elements\nbased on the `componentsObject` passed to the Macro function.\nUsing the Banner component above would look something like the following.\n\n```jsx\nimport Banner from './Banner'\n\nconst App = () =\u003e (\n  \u003cBanner\u003e\n    \u003cBanner.Heading\u003eHello\u003c/Banner.Heading\u003e\n    \u003cBanner.Subhead\u003eSubhead\u003c/Banner.Subhead\u003e\n  \u003c/Banner\u003e\n)\n```\n\n### componentsObject\n\nThe components object is used to defined which components the macro component will accept as children.\n\n### elementFunction\n\nThe element function is similar to a React component, but receives an elements object as its first argument and props as its second one.\nThe elements object is created from its children and is intended to make encapsulating composition and element structures easier.\n\nWithin the macro component, the element function is called with the elements object and props: `elementFunction(elementsObject, props)`.\n\n```jsx\n// example\nconst elFunc = ({ Heading, Text, }, props) =\u003e (\n  \u003cheader\u003e\n    {Heading}\n    {Text}\n  \u003c/header\u003e\n)\n\nconst Heading = styled.h2``\nconst Text = styled.div``\n\nconst componentsObj = {\n  Heading,\n  Text\n}\n\nconst SectionHeader = Macro(componentsObj)(elFunc)\n```\n\n### Omitting children\n\nFor any element not passed as a child to the macro component,\nthe element function will render `undefined` and React will not render that element.\nThis is useful for conditionally omitting optional children\n\n```jsx\nconst macro = Macro({ Icon, Text, CloseButton })\n\nconst Message = macro({\n  Icon,\n  Text,\n  CloseButton\n}) =\u003e (\n  \u003cFlex p={2} bg='lightYellow'\u003e\n    {Icon}\n    {Text}\n    \u003cBox mx='auto' /\u003e\n    {CloseButton}\n  \u003c/Flex\u003e\n)\n```\n\n```jsx\nimport Message from './Message'\n\nconst { Text, CloseButton } = Message\n\n// Omitting the Icon child element will render Message without an icon.\nconst message = (\n  \u003cMessage\u003e\n    \u003cText\u003e{props.message}\u003c/Text\u003e\n    \u003cCloseButton\n      onClick={props.dismissMessage}\n    /\u003e\n  \u003c/Message\u003e\n)\n```\n\n### Props passed to the root component\n\nThe second argument passed to the element function allows you to pass props to the root element or any other element within the component.\n\n```jsx\nconst macro = Macro({ Image, Text })\n\nconst Card = macro(({\n  Image,\n  Text\n}, props) =\u003e (\n  \u003cBox p={2} bg={props.bg}\u003e\n    {Image}\n    {Text}\n  \u003c/Box\u003e\n))\n```\n\n```jsx\n// example usage\n\u003cCard bg='tomato'\u003e\n  \u003cCard.Image src='kittens.png' /\u003e\n  \u003cCard.Text\u003eMeow\u003c/Card.Text\u003e\n\u003c/Card\u003e\n```\n\n### Clone Component\n\nTo apply default props to the elements passed in as children, use the Clone component in an element function.\n\n```jsx\nimport Macro, { Clone } from 'macro-components'\nimport { Heading, Text } from './ui'\n\nconst macro = Macro({ Heading, Text })\n\nconst Header = macro(({ Heading, Text }) =\u003e (\n  \u003cBox p={2}\u003e\n    \u003cClone\n      element={Heading}\n      fontSize={6}\n      mb={2}\n    /\u003e\n    \u003cClone\n      element={Text}\n      fontSize={3}\n    /\u003e\n  \u003c/Box\u003e\n))\n```\n\n### Using a Component Multiple Times\n\nTo use the same component twice, give it a unique key in the componentsObject.\n\n```jsx\nimport React from 'react'\nimport Macro from 'macro-components'\nimport { Heading } from './ui'\n\nconst macro = Macro({\n  Heading: Heading,\n  Subhead: Heading\n})\n\nconst Header = macro(({ Heading, Subhead }) =\u003e (\n  \u003cBox p={2}\u003e\n    {Heading}\n    {Subhead}\n  \u003c/Box\u003e\n))\n```\n\n```jsx\n\u003cHeader\u003e\n  \u003cHeader.Heading\u003eHello\u003c/Header.Heading\u003e\n  \u003cHeader.Subhead\u003eSubhead\u003c/Header.Subhead\u003e\n\u003c/Header\u003e\n```\n\n---\n\n### Alternatives\n\nTo create layout components that are **not** coupled to specific child components, using props or ordered children is probably a simpler approach.\n\nThe solutions below allow you to pass any arbitrary components as props or children.\n\nSee [this discussion](https://github.com/jxnblk/macro-components/issues/3) for more.\n\n```jsx\n// using custom props\nconst MyLayout = ({\n  left,\n  right\n}) =\u003e (\n  \u003cFlex\u003e\n    \u003cBox width={128}\u003e\n      {left}\n    \u003c/Box\u003e\n    \u003cBox width={1}\u003e\n      {right}\n    \u003c/Box\u003e\n  \u003c/Flex\u003e\n)\n\n\u003cMyLayout\n  left={(\n    \u003cImage src='kitten.png' /\u003e\n  )}\n  right={(\n    \u003cText\u003eMeow\u003c/Text\u003e\n  )}\n/\u003e\n```\n\n```jsx\n// using ordered children\nconst Header = props =\u003e {\n  const [ first, second ] = React.Children.toArray(props.children)\n  return (\n    \u003cBox p={3}\u003e\n      {first}\n      {second}\n    \u003c/Box\u003e\n  )\n}\n\n\u003cHeader\u003e\n  \u003cHeading\u003eFirst\u003c/Heading\u003e\n  \u003cText\u003eSecond\u003c/Text\u003e\n\u003c/Header\u003e\n```\n\n```jsx\n// using a children object\nconst Header = ({\n  children: {\n    left,\n    right\n  }\n}) =\u003e (\n  \u003cFlex\u003e\n    \u003cBox\u003e\n      {left}\n    \u003c/Box\u003e\n    \u003cBox width={1}\u003e\n      {right}\n    \u003c/Box\u003e\n  \u003c/Flex\u003e\n)\n\n\u003cHeader\u003e\n  {{\n    left: (\n      \u003cImage src='kitten.png' /\u003e\n    ),\n    right: (\n      \u003cText\u003eMeow\u003c/Text\u003e\n    )\n  }}\n\u003c/Header\u003e\n```\n\n---\n\n#### Related\n\n- [styled-components][sc]\n- [glamorous][glamorous]\n- [emotion][emotion]\n- [styled-system](https://github.com/jxnblk/styled-system)\n- [system-components](https://github.com/jxnblk/system-components)\n- *MediaObject* example based on: [The media object saves hundreds of lines of code](http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/)\n\n[sc]: https://github.com/styled-components/styled-components\n[glamorous]: https://github.com/paypal/glamorous\n[emotion]: https://github.com/emotion-js/emotion\n\n[MIT License](LICENSE.md)\n","funding_links":[],"categories":["JavaScript","Libraries and components"],"sub_categories":["React"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxnblk%2Fmacro-components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjxnblk%2Fmacro-components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxnblk%2Fmacro-components/lists"}