Skip to main content

​
Installation

Get started with Grauity by installing the package and configuring your project.

​
Prerequisites

Before installing Grauity, ensure your project meets these requirements: 
{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9"
  }
}
Grauity requires Node.js 18.0.0 or higher and npm 9 or higher.

​
Step 1: Install the package

1

Install Grauity and peer dependencies

Install @newtonschool/grauity along with its required peer dependencies:
npm install @newtonschool/grauity react react-dom styled-components
Peer dependencies:
  • react >= 18.2.0
  • react-dom >= 18.2.0
  • styled-components >= 6.1.14
2

Import icon styles

To use Grauity’s icon system, import the icon CSS in your root-level stylesheet or entry file.In your global-styles.scss or main CSS/SCSS file:
global-styles.scss
@import '~@newtonschool/grauity/dist/css/index.scss';
Or in your main JavaScript/TypeScript entry file:
main.tsx
import '@newtonschool/grauity/dist/css/index.scss';
Make sure your build tool supports CSS/SCSS imports. For Webpack, you’ll need style-loader, css-loader, and sass-loader configured.

​
Step 2: Set up the theme provider

1

Wrap your app with GrauityThemeProvider

Grauity uses GrauityThemeProvider to enable theming support. Wrap your root component with this provider:
App.tsx
import React, { useState } from 'react';
import { GrauityThemeProvider } from '@newtonschool/grauity';

function App() {
  const [currentTheme, setCurrentTheme] = useState('light');

  return (
    <GrauityThemeProvider rootThemeScopeTheme={currentTheme}>
      {/* Your app components */}
    </GrauityThemeProvider>
  );
}

export default App;
The rootThemeScopeTheme prop should be set to your current global theme ("light" or "dark"). This enables scoped theming with the NSThemeScope component.
2

Understanding theming (optional)

Without the GrauityThemeProvider, only foundational (theme-agnostic) CSS variables will be available. The provider adds:
  • Global theme context - Access to light/dark theme variables
  • Theme scoping - Use NSThemeScope to apply different themes to sections
  • Dynamic theming - Switch themes at runtime
The provider internally uses styled-components’ ThemeProvider and injects both light and dark theme configurations:
import { 
  GrauityThemeProvider,
  NS_LIGHT_THEME_CONFIG,
  NS_DARK_THEME_CONFIG 
} from '@newtonschool/grauity';

// Custom theme configuration (optional)
const customThemeConfig = {
  light: NS_LIGHT_THEME_CONFIG,
  dark: NS_DARK_THEME_CONFIG,
};

function App() {
  return (
    <GrauityThemeProvider 
      themeConfig={customThemeConfig}
      rootThemeScopeTheme="light"
    >
      {/* Your app */}
    </GrauityThemeProvider>
  );
}

​
Step 3: Import and use components

You’re ready to use Grauity components! Import them from the main package:
Example.tsx
import { NSButton, NSTextField, NSModal } from '@newtonschool/grauity';

function Example() {
  return (
    <div>
      <NSButton variant="primary" color="brand">
        Click me
      </NSButton>
      
      <NSTextField
        name="email"
        label="Email address"
        placeholder="Enter your email"
      />
    </div>
  );
}

​
TypeScript configuration

Grauity is built with TypeScript and includes type definitions. No additional setup is required, but ensure your tsconfig.json includes:
tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

​
Build tool configuration

​
Webpack

If you’re using Webpack, ensure you have loaders for SCSS: 
npm install --save-dev style-loader css-loader sass-loader sass
webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: ['style-loader', 'css-loader', 'sass-loader'],
      },
    ],
  },
};

​
Vite

For Vite, install sass: 
npm install --save-dev sass
Vite will automatically handle SCSS imports.

​
Next.js

For Next.js, install sass: 
npm install --save-dev sass
Then import the icon styles in _app.tsx:
pages/_app.tsx
import '@newtonschool/grauity/dist/css/index.scss';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

export default MyApp;
Styled-components with Next.js: You’ll need to configure styled-components for SSR. See the styled-components Next.js guide.

​
Theme scoping (advanced)

Use NSThemeScope to apply different themes to specific sections of your app: 
import { NSThemeScope, NSButton } from '@newtonschool/grauity';

function Example() {
  return (
    <div>
      {/* Light theme section */}
      <NSThemeScope applyTheme="light">
        <NSButton variant="primary">Light button</NSButton>
      </NSThemeScope>

      {/* Dark theme section */}
      <NSThemeScope applyTheme="dark">
        <NSButton variant="primary">Dark button</NSButton>
      </NSThemeScope>

      {/* Inverted theme (if parent is light, this becomes dark) */}
      <NSThemeScope invert>
        <NSButton variant="primary">Inverted button</NSButton>
      </NSThemeScope>
    </div>
  );
}
Use the as prop on NSThemeScope to avoid adding an extra div wrapper:
<NSThemeScope as="section" applyTheme="dark">
  {/* Content */}
</NSThemeScope>

​
Legacy theme classes (optional)

If you’re not using GrauityThemeProvider, you can control theming with CSS classes: 
// Light theme
<body className="grauity-theme-light">
  {/* App content */}
</body>

// Dark theme
<body className="grauity-theme-dark">
  {/* App content */}
</body>
This approach is considered legacy. We recommend using GrauityThemeProvider and NSThemeScope for better theme management.

​
Verify installation

Create a simple test component to verify everything is working:
Test.tsx
import React from 'react';
import { NSButton, NSIcon } from '@newtonschool/grauity';

function Test() {
  return (
    <div style={{ padding: '20px' }}>
      <NSButton 
        variant="primary" 
        color="brand"
        icon="sparkle"
        onClick={() => alert('Grauity is working!')}
      >
        Test Grauity
      </NSButton>
      
      <div style={{ marginTop: '20px' }}>
        <NSIcon name="check-circle" size="32" color="var(--color-success-base)" />
        <span>Installation successful!</span>
      </div>
    </div>
  );
}

export default Test;
If you see a styled button with an icon, congratulations! Grauity is installed correctly.

​
Next steps

Quickstart tutorial

Build your first component with Grauity

Component documentation

Explore all available components

​
Troubleshooting

Make sure you’ve imported the icon CSS:
@import '~@newtonschool/grauity/dist/css/index.scss';
Also verify that your build tool (Webpack, Vite, etc.) is configured to handle SCSS imports.
Ensure you have the correct version of styled-components installed:
npm install styled-components@^6.1.14
For Next.js, make sure you’ve configured SSR support for styled-components.
If you’re getting TypeScript errors, ensure your tsconfig.json has:
  • "jsx": "react-jsx" or "jsx": "react"
  • "esModuleInterop": true
  • "skipLibCheck": true
Make sure you’ve wrapped your app with GrauityThemeProvider:
<GrauityThemeProvider rootThemeScopeTheme="light">
  <App />
</GrauityThemeProvider>

Build docs developers (and LLMs) love

Get started for freeTalk to us