!! Shamrock UX is still under active development and may change substantially before its release !!

Getting Started

Create a Tailwind CSS Project

First, follow the instructions in the Tailwind CSS installation guide to create a React with Tailwind CSS. I recommend using Gatsby since it is very fast and easy to use.

Install Shamrock UX

Next, you'll need to install shamrock-ux into your project as a development dependency using npm:

npm i shamrock-ux -D

Create your Shamrock config file

To configure Shamrock UX, you'll need to pass your configuration to both Tailwind CSS and React. To do this, I highly recommend using a configuration file named shamrock.config.js and placed next to your React site's JSX entry point.


If you're using Gatsby, you should put this file next to your Gatsby config files so that you can import it from gatsby-browser.js and gatsby-ssr.js.

If you're using Create React App, you should put this file in your src folder so that you can import it from your index.js or App.js file.


Here's a template for getting started with shamrock.config.js:

module.exports = {
    colors: {
        ramps: {
            //Swap these colors with your brand's colors. Each has a light and dark variant, for use in light and dark mode respectively
            ui: {
                //Color used for brand-themed elements (like active buttons)
                brandElement: {
                    light: "#2c6a40",
                    dark: "#44b56a"
                },
                //Color used when hovering over a brand-themed element
                brandElementHover: {
                    light: "#2e7847",
                    dark: "#3ca35f"
                }
            },
            type: {
                //Color used for brand-themed text (like links)
                brand: {
                    light: "#217d43",
                    dark: "#37aa60"
                },
                //Color used for text on top of brand-themed elements
                brandElement: {
                    light: "#ededed",
                    dark: "#03210d"
                }
            }
        }
    }
};

Configure Tailwind CSS

You'll need to apply Shamrock UX styles to your project by adding the preset in your tailwind.config.js file:

module.exports = {
  mode: "jit",
  purge: {
    content: ['./src/**/*.{js,jsx,ts,tsx}', './public/index.html', './node_modules/shamrock-ux/lib/react/**/*.js'],
    options: {
      safelist: [/data-theme/] //Prevent theme CSS rules (which aren't explicitly used) from being tree-shaken
    }
  },
  //TODO: Replace the placeholder below to point to your Shamrock UX config file
  presets: [ require("shamrock-ux/lib/tailwind")(require("./PATH_TO_YOUR_SHAMROCK_CONFIG.js")) ]
};

Add the Shamrock UX Root to React

Finally, you'll need to add the Shamrock UX Root provider to your React project to include global Shamrock UX listeners, themes, contexts, and more. The Root element also needs your Shamrock UX config, so you'll need to import that here as well.

For Gatsby:

//In both gatsby-browser.js AND gatsby-ssr.js
import React from "react";
import { Root } from "shamrock-ux";

//TODO: Replace the placeholder below to point to your Shamrock UX config file
import shamrockConfig from "./PATH_TO_YOUR_SHAMROCK_CONFIG.js";

// ...

export const wrapRootElement = ({ element }) => {
    return (
        <Root config={shamrockConfig}>{element}</Root>
    );
};

// ...

For Create React App:

import React from 'react';
import { Root } from "shamrock-ux";

//TODO: Replace the placeholder below to point to your Shamrock UX config file
import shamrockConfig from "./PATH_TO_YOUR_SHAMROCK_CONFIG.js";

// ...

ReactDOM.render(
  <React.StrictMode>
    <Root config={shamrockConfig}>
      <App />
    </Root>
  </React.StrictMode>,
  document.getElementById('root')
);

// ...

Start your project

You're finished! Now, you can just start your project and use Shamrock UX and Tailwind CSS:

npm start

Navigation

Navigation works mostly as you would expect in Shamrock UX, however, there are a few important quirks to keep in mind.

Shamrock UX currently has 2 page navigation elements: Navbar and Sidebar. You cannot use more than one of each, and you cannot change their size or position. There are also some additional restrictions on where each element needs to be loaded.

Navbar

The Navbar component should be placed before any vertical margin/padding is applied. All page content that shows under the Navbar should be placed within the Navbar component.


If you're using Gatsby, you'll need to use some extra steps to prevent your Navbar from behaving strangely. For this, I recommend using the Navbar component in a wrapPageElement in both gatsby-browser.js and gatsby-ssr.js:

//In both gatsby-browser.js AND gatsby-ssr.js
import React from "react";
import { Navbar } from "shamrock-ux";

// ...

export const wrapPageElement = ({ element }) => {
    //IMPORTANT: In gatsby-ssr.js, delete the items prop from the Navbar. The items will be rendered in after page hydration.
    return (
        <Navbar title="..." logo="..." items={/* ... */}>{element}</Navbar>
    );
};

// ...

Sidebar

If you are using a Sidebar, you must also use a Navbar. The Sidebar component must be placed within the Navbar component before any additional margin/padding has been applied.