{"id":13515494,"url":"https://github.com/braposo/graphql-css","last_synced_at":"2025-04-12T22:19:16.459Z","repository":{"id":30491719,"uuid":"124787700","full_name":"braposo/graphql-css","owner":"braposo","description":"A blazing fast CSS-in-GQL™ library.","archived":false,"fork":false,"pushed_at":"2022-12-09T08:25:18.000Z","size":749,"stargazers_count":674,"open_issues_count":18,"forks_count":7,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-04T03:08:09.923Z","etag":null,"topics":["css","css-in-gql","glamorous","graphql","react","styleguide","styles"],"latest_commit_sha":null,"homepage":"https://codesandbox.io/s/5vljjr4zo4","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/braposo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-11T18:50:16.000Z","updated_at":"2025-03-30T17:44:20.000Z","dependencies_parsed_at":"2023-01-14T17:15:25.085Z","dependency_job_id":null,"html_url":"https://github.com/braposo/graphql-css","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braposo%2Fgraphql-css","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braposo%2Fgraphql-css/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braposo%2Fgraphql-css/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braposo%2Fgraphql-css/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/braposo","download_url":"https://codeload.github.com/braposo/graphql-css/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637893,"owners_count":21137564,"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","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":["css","css-in-gql","glamorous","graphql","react","styleguide","styles"],"created_at":"2024-08-01T05:01:11.981Z","updated_at":"2025-04-12T22:19:16.420Z","avatar_url":"https://github.com/braposo.png","language":"JavaScript","readme":"# \u003ca href=\"https://github.com/braposo/graphql-css\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/38172/37561184-50288d50-2a40-11e8-9f19-e23c4ca61c32.png\" width=\"376\" /\u003e\u003c/a\u003e\n\n`graphql-css` is a blazing fast CSS-in-GQL™ library that converts GraphQL queries into styles for your components.\n\nComes with a bunch of utilities so it's easy to integrate with your favourite way of building components.\n\n[![Build Status][build-badge]][travis]\n[![Code Coverage][coverage-badge]][coverage]\n[![npm version][version-badge]][npm]\n[![npm downloads][downloads-badge]][npm]\n[![gzip size][size-badge]][size]\n[![MIT License][license-badge]][license]\n\n![Module format][modules-badge]\n![Prettier format][prettier-badge]\n[![PRs Welcome][prs-badge]][prs]\n![Blazing Fast][fast-badge]\n![Modern][modern-badge]\n![Enterprise Grade][enterprise-badge]\n\n## Installation\n\n```bash\nnpm install graphql-css\n# or\nyarn add graphql-css\n```\n\n#### Dependencies\n\n`graphql-css` requires `graphql` to be installed as a peer dependency. It's compatible with [React hooks](https://reactjs.org/docs/hooks-intro.html) so you can use it with React's latest version.\n\n## Quick start\n\n```jsx\nimport useGqlCSS from \"graphql-css\";\nimport styles from \"your-style-guide\";\n\nconst App = () =\u003e {\n    const { styled } = useGqlCSS(styles);\n    const H2 = styled.h2`\n        {\n            typography {\n                h2\n            }\n            marginLeft: spacing {\n                xl\n            }\n            color: colors {\n                green\n            }\n        }\n    `;\n    return \u003cH2\u003eThis is a styled text\u003c/H2\u003e;\n};\n```\n\n[![Edit graphql-css][codesandbox-badge]][codesandbox]\n\n## API\n\nBy default, `graphql-css` exports a hook-like function called `useGqlCSS`. \n\nIt also exports a couple of other utilities:\n\n-   `GqlCSS`: a component that provides the same declarative API\n-   `gql`: the default export from `graphql-tag` so you don't have to install it if only using graphql-css\n\n### useGqlCSS\n\nThe main export is the `useGqlCSS` function that should be used in most cases. It provides these utilities:\n\n-   `styled`: a styled-component inspired function to create components from gqlCSS queries\n-   `getStyles`: a function to extract styles to an object\n-   `GqlCSS`: a component that encapsulates the `styled` functionality\n\n`useGqlCSS` needs to be initialised with the styles from the styleguide in a JSON format (check examples folder for a detailed example).\n\nHere's how you can use it to create a new component with `styled`:\n\n```jsx\nimport useGqlCSS from \"graphql-css\";\n...\nconst { styled } = useGqlCSS(styles);\nconst Text = styled.p`\n    {\n        typography {\n            fontSize: scale {\n                l\n            }\n        }\n    }\n`;\n...\n\u003cText\u003eThis is a styled text\u003c/Text\u003e\n```\n\nalternatively, you can also return the styles as an object with `getStyles` so you can use it with other CSS-in-JS libraries:\n\n```jsx\nimport useGqlCSS, { gql } from \"graphql-css\";\nimport styled from \"@emotion/styled\";\n...\nconst query = gql`\n    {\n        color: colors {\n            green\n        }\n    }\n`;\nconst { getStyles } = useGqlCSS(styles);\nconst StyledComponent = styled.div(getStyles(query));\n```\n\nIf you want to keep the declarative API you can also use the `GqlCSS`, which is an exact match to the main `GqlCSS` component exported by this library. The only difference is that the `useGqlCSS` version already has the styles initialised.\n\n```jsx\nimport useGqlCSS, { gql } from \"graphql-css\";\n...\nconst { GqlCSS } = useGqlCSS(styles);\nconst query = gql`\n    {\n        typography {\n            h2\n        }\n    }\n`;\n...\n\u003cGqlCSS query={query} component=\"h2\"\u003eThis is a styled text\u003c/GqlCSS\u003e\n```\n\nPlease check the `GqlCSS` section below for a detailed reference.\n\n### GqlCSS\n\n`\u003cGqlCSS\u003e` component allows for a more declarative API and accepts these props:\n\n| Prop      | Type             | Default | Definition                                      |\n| --------- | ---------------- | ------- | ----------------------------------------------- |\n| styles    | object           |         | The styleguide object with all the rules        |\n| query     | gql              |         | The gql query to get the styles                 |\n| component | string \\|\\| node | \"div\"   | HTML element or React component to be displayed |\n\nAll the remaining props are passed to the generated component. Here are some examples:\n\n```jsx\n...\n\u003cGqlCSS styles={styles} query={query}\u003eThis is a styled text\u003c/GqlCSS\u003e\n\u003cGqlCSS styles={styles} query={queryH1} component=\"h1\"\u003eThis is a styled H1 heading\u003c/GqlCSS\u003e\n...\n```\n\n## Styles object\n\nThe styles object is a valid JSON object that is used to define the styleguide of your project. Usually it includes definitions for colors, spacing, typography, etc.\n\n```js\nconst base = 4;\nconst styles = {\n    typography: {\n        scale: {\n            s: base * 3,\n            base: base * 4,\n            m: base * 6,\n            l: base * 9,\n            xl: base * 13,\n            xxl: base * 20,\n            unit: \"px\",\n        },\n        weight: {\n            thin: 300,\n            normal: 400,\n            bold: 700,\n            bolder: 900,\n        },\n    },\n    spacing: {\n        s: base,\n        base: base * 2,\n        m: base * 4,\n        l: base * 6,\n        xl: base * 8,\n        xxl: base * 10,\n        unit: \"px\",\n    },\n    colors: {\n        blue: \"blue\",\n        green: \"green\",\n        red: \"red\",\n    },\n};\n```\n\nThis is completely up to you and one of the big advantages of using `graphql-css` as you can adapt it to your needs. As long as the styles and the queries match their structure, there shouldn't be much problem.\n\nYou can also specify the unit of each property by definining the `unit` key.\n\n```js\nscale: {\n    s: base * 3,\n    base: base * 4,\n    m: base * 6,\n    l: base * 9,\n    xl: base * 13,\n    xxl: base * 20,\n    unit: \"em\"\n},\n```\n\n## Building the GraphQL query\n\nThe GraphQL query follows the structure of the styles object with a few particular details. When building the query you need to alias the values you're getting from the style guide to the correspondent CSS property. Here's a quick example:\n\n```js\n{\n    typography {\n        fontSize: scale {\n            xl\n        }\n        fontWeight: weight {\n            bold\n        }\n    }\n}\n```\n\nThis also means that you can reuse the same query by using different alias:\n\n```js\n{\n    marginLeft: spacing {\n        l\n    }\n    paddingTop: spacing {\n        xl\n    }\n}\n```\n\n#### Using fragments\n\nBecause _This is just GraphQL™_, you can also create fragments that can then be included in other queries:\n\n```js\nconst h1Styles = gql`\n    fragment H1 on Styles {\n        base {\n            typography {\n                fontSize: scale {\n                    xl\n                }\n                fontWeight: weight {\n                    bold\n                }\n            }\n        }\n    }\n`;\n\nconst otherH1Styles = gql`\n    ${h1Styles}\n    {\n        ...H1\n        base {\n            color: colors {\n                blue\n            }\n        }\n    }\n`;\n```\n\nThis is a powerful pattern that avoids lots of repetitions and allows for a bigger separation of concerns.\n\n#### Defining custom unit\n\nYou can also override the pre-defined unit directly in your query by using the argument `unit`:\n\n```js\n{\n    marginLeft: spacing(unit: \"em\") {\n        l\n    }\n    paddingTop: spacing {\n        xl\n    }\n}\n```\n\nThis will return `{ marginLeft: \"24em\", paddingTop: \"32px\" }`.\n\n#### Using style variations (theming)\n\nOne of the big advantages of CSS-in-GQL™ is that you can use the power of variables to build custom queries. In `graphql-css` that means that we can easily define variants (think themes) for specific components.\n\nLet's start with this style definition file:\n\n```js\nconst styles = {\n    theme: {\n        light: {\n            button: {\n                // button light styles\n            },\n        },\n        dark: {\n            button: {\n                // button dark styles\n            },\n        },\n    },\n};\n```\n\nWe now have two options to handle theming, first using the `styled` function from `useGqlCSS`:\n\n```jsx\nimport useGqlCSS, { gql } from \"graphql-css\";\n...\nconst { styled } = useGqlCSS(styles);\nconst Button = styled.button`\n    {\n        theme(variant: ${props =\u003e props.variant}) {\n            button\n        }\n    }\n`;\n...\n\u003cButton variant=\"dark\"\u003eSome text\u003c/Button\u003e\n```\n\nAlternatively, we can use GraphQL variables instead by using `getStyles`:\n\n```jsx\nimport useGqlCSS, { gql } from \"graphql-css\";\nimport styled from \"@emotion/styled\";\n...\nconst { getStyles } = useGqlCSS(styles);\nconst query = gql`\n    {\n        theme(variant: $variant) {\n            button\n        }\n    }\n`;\nconst LightButton = styled.button(getStyles(query, { variant: \"light\" }));\n...\n\u003cLightButton\u003eSome text\u003c/LightButton\u003e\n```\n\n## Developing\n\nYou can use `yarn run dev` to run it locally, but we recommend using the [CodeSandbox playground][codesandbox] for development.\n\n## Contributing\n\nPlease follow our [contributing guidelines](https://github.com/braposo/graphql-css/blob/master/CONTRIBUTING.md).\n\n## License\n\n[MIT](https://github.com/davidgomes/graphql-css/blob/master/LICENSE)\n\n[npm]: https://www.npmjs.com/package/graphql-css\n[license]: https://github.com/braposo/graphql-css/blob/master/LICENSE\n[prs]: http://makeapullrequest.com\n[size]: https://unpkg.com/graphql-css/dist/graphql-css.min.js\n[version-badge]: https://img.shields.io/npm/v/graphql-css.svg?style=flat-square\n[downloads-badge]: https://img.shields.io/npm/dm/graphql-css.svg?style=flat-square\n[license-badge]: https://img.shields.io/npm/l/graphql-css.svg?style=flat-square\n[fast-badge]: https://img.shields.io/badge/🔥-Blazing%20Fast-red.svg?style=flat-square\n[modern-badge]: https://img.shields.io/badge/💎-Modern-44aadd.svg?style=flat-square\n[enterprise-badge]: https://img.shields.io/badge/🏢-Enterprise%20Grade-999999.svg?style=flat-square\n[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[size-badge]: http://img.badgesize.io/https://unpkg.com/graphql-css/dist/graphql-css.min.js?compression=gzip\u0026style=flat-square\n[prettier-badge]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square\n[build-badge]: https://img.shields.io/travis/braposo/graphql-css.svg?style=flat-square\n[travis]: https://travis-ci.org/braposo/graphql-css\n[coverage-badge]: https://img.shields.io/codecov/c/github/braposo/graphql-css.svg?style=flat-square\n[coverage]: https://codecov.io/github/braposo/graphql-css\n[modules-badge]: https://img.shields.io/badge/module%20formats-umd%2C%20cjs%2C%20esm-green.svg?style=flat-square\n[codesandbox-badge]: https://codesandbox.io/static/img/play-codesandbox.svg\n[codesandbox]: https://codesandbox.io/s/5vljjr4zo4\n","funding_links":[],"categories":["JavaScript","📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraposo%2Fgraphql-css","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbraposo%2Fgraphql-css","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraposo%2Fgraphql-css/lists"}