@graphprotocol/gds-react

React components for The Graph Design System.

Installation

pnpm add @graphprotocol/gds-react

Peer Dependencies

This package requires the following peer dependencies:

pnpm add react react-dom react-is tailwindcss

Setup

1. Ensure Tailwind CSS is installed and configured in your project (preferably with Vite).

2. Replace the tailwind import in your main CSS file with @graphprotocol/gds-react:

   - @import 'tailwindcss';
   + @import '@graphprotocol/gds-react';

3. Register source paths relative to your CSS file:

     @import '@graphprotocol/gds-react';
   + @source '../src';

   @graphprotocol/gds-react disables Tailwind's default content scanning as an optimization measure, so you must explicitly register your source paths using @source directives. Make sure to include all paths where Tailwind classes are used.

4. Wrap your app with GDSProvider:

   import { GDSProvider } from '@graphprotocol/gds-react'
   
   function App() {
     return <GDSProvider>{/* your app */}</GDSProvider>
   }

   The provider accepts optional props:

   • theme - 'dark' (default), 'light', or 'system'
   • direction - 'ltr' (default) or 'rtl'
   • language - defaults to 'en' as long as direction is 'ltr'

5. Optional recommended steps:

   • If you use VS Code (or a fork like Cursor), install the Tailwind CSS IntelliSense extension.

     • If it doesn't automatically recognize GDS-specific classes like text-16, it is likely because it cannot find the CSS file that registers GDS's Tailwind theme and plugin (which can happen in monorepos or projects with unusual/complex directory structures). Add the following to .vscode/settings.json and customize the paths to match your project:

       {
         "tailwindCSS.experimental.configFile": {
           "packages/ui/globals.css": "packages/ui/**"
         }
       }

   • If you use Prettier, install prettier-plugin-tailwindcss and add it to your config (e.g. .prettierrc):

     {
       "plugins": ["prettier-plugin-tailwindcss"],
       "tailwindPreserveWhitespace": true,
       "tailwindFunctions": ["cn"],
       "overrides": [
         {
           "files": "packages/ui/**",
           "options": {
             "tailwindStylesheet": "packages/ui/globals.css"
           }
         }
       ]
     }

     Make sure to customize the paths to match your project (files should match any file that contains classes, and tailwindStylesheet should point to your main CSS file, from which you imported GDS).

That's it, you're ready to use GDS utilities and components!

Usage

import { Button, Card, Input } from '@graphprotocol/gds-react'

function Example() {
  return (
    <Card>
      <Input label="Enter text..." />
      <Button variant="primary">Submit</Button>
    </Card>
  )
}

Exports

• @graphprotocol/gds-react - Styled components
• @graphprotocol/gds-react/base - Base/primitive (mostly unstyled) components
• @graphprotocol/gds-react/hooks - React hooks that are useful when working with GDS components
• @graphprotocol/gds-react/icons - React components for gds-icons
• @graphprotocol/gds-react/utils - React-specific utility functions

License

MIT