Quick Start

How to use avocado-ui in your React project

Usage

After installation, avocado-ui is now available in your project. Import your desired component from the @avocado-ui/react package like so and you're good to go!

import { Button } from "@avocado-ui/react";
render(
  <>
    <Button>Example</Button>
  </>
);

import { Button } from "@avocado-ui/react";
render(
  <>
    <Button>Example</Button>
  </>
);

Theming

Theming in Avocado works by passing in strategic properties that replace their default values in the design system. The plan is to make all tokens customizable, but only colors are customizable at the moment.

Here's an example of how to customizable the primary and secondary colors in the design system.

import { Button, ThemeProvider } from "@avocado-ui/react";

const customTheme = {
  primaryColor: "#3f00ff",
  secondaryColor: "#6330ff",
};

render(
  <ThemeProvider theme={customTheme}>
    <Button>Example</Button>
  </ThemeProvider>
);

Passing this custom theme into the theme changes the theme of our design system. Here's a codesandbox demo showing an example of this working.

You have to be careful when using the primary & secondary colors. They have to atleast look good together for your design system to be decent.

Other Frameworks

Create React App setup

Set up Avocado in CRA by wrapping the whole application inside the root component. It'll look something like this...

// index.js
import { StrictMode } from "react";
import { ThemeProvider } from "@avocado-ui/react";
import ReactDOM from "react-dom";

import App from "./App";

const theme = {
  primaryColor: "#3f00ff",
  secondaryColor: "#6330ff",
};

const rootElement = document.getElementById("root");
ReactDOM.render(
  <StrictMode>
    <ThemeProvider theme={theme}>
      <App />
    </ThemeProvider>
  </StrictMode>,
  rootElement
);

You can see this live in this codesandbox.

NextJS setup

The key to setting up Avocado in NextJS lies in the _app.js file. This might sound tricky to you if you're new to Nextjs, but you only have to understand that _app.js wraps around all pages in the app.

Here's an example of setting up the Avocado theme in a nextjs application

// _app.js
import { ThemeProvider } from "@avocado-ui/react";
import "../styles.css";

const theme = {
  primaryColor: "#3f00ff",
  secondaryColor: "#6330ff",
};

export default function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider theme={theme}>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

You can see this demo live on this codesandbox.

Gatsby setup

Todo

Gatsby shares a lot of similiarities with Nextjs. The most prominent being that they can both render React on the server and ship HTML to the browser.

Setting up Avocado in Gatsby involves 2 files - gatsby-browser.js and gatsby-ssr.js. Here's an example of using Avocado in Gatsby...

// gatsby-browser.js
import React from "react";
import { ThemeProvider } from "@avocado-ui/react";

const theme = {
  primaryColor: "#3f00ff",
  secondaryColor: "#6330ff",
};

export const wrapRootElement = ({ element }) => {
  return <ThemeProvider theme={theme}>{element}</ThemeProvider>;
};

// gatsby-browser.js
import React from "react";
import { ThemeProvider } from "@avocado-ui/react";

const theme = {
  primaryColor: "#3f00ff",
  secondaryColor: "#6330ff",
};

export const wrapRootElement = ({ element }) => {
  return <ThemeProvider theme={theme}>{element}</ThemeProvider>;
};

Here's an codesandbox example of Avocado on Gatsby.

It feels strange the we have to have the same contents in gatsby-browser.js & gatsby-ssr.js. I've tried having removing one of them, but it just janks after then.