@tiger-ui/react v2.0.0

Tiger UI React is a CSS-IN-JS library. It leverages ancillary UI tools like Emotion React and allows you to easily create stylizable and flexible UI components. Tiger UI React aims to provide you with useful tools to easily create a Design System.

Installation

Install the package in your project directory with:

npm:

npm install @tiger-ui/react

yarn:

yarn add @tiger-ui/react

Docs

Introduction

Tiger UI React is a React.JS component tool that allows you to write your stylized components in a fast, practical and readable way. It offers powerful CSS-IN-JS support using the Emotion React library in its infrastructure. This library aims to make it easier for you to create your own design system.

Table of Contents

• Getting Started
• Element Props
  • Responsive Prop Value
• Extending Elements
• Defaults Attributes / Props
• Children Content
• Theming
  • Create Theme
  • Default Theme Options
  • Color System
  • Typescript - Theme Type Declaration
• CSSX / Custom Styling

Getting Started

The component logic on tiger-ui/react is based on html elements. The simplest way to create a customizable element is as follows:

import { createElement } from '@tiger-ui/react'

const Container = createElement('div')({
  style: {
    padding: '6rem',
  },
});

const Button = createElement('button')({
  style: {
    backgroundColor: 'green',
    color: 'white',
    border: 'none',
    padding: '0.7rem 2rem',
    borderRadius: '0.6rem',
    cursor: 'pointer',
    fontWeight: 'bold',
    ':hover': {
      backgroundColor: 'darkgreen',
    },
  },
});

export default function Page() {
  return (
    <Container>
      <Button>Click</Button>
    </Container>
  )
}

Output:

Element Props

You can add props that change the style state of the elements you create. You can use this feature in two different ways:

Both ways used above give the same result. Depending on your use case, you can use either method.

Responsive Prop Value

It is also possible to assign values responsively while using the props you added.

import { createElement } from '@tiger-ui/react'

const Wrapper = createElement('div')({
  style: {
    display: 'flex',
    justifyContent: 'center',
    padding: '6rem',
  },
});

interface ButtonProps {
  variant: 'contained' | 'outlined';
}

const Button = createElement('button')<ButtonProps>({
  style: {
    padding: '0.7rem 2rem',
    borderRadius: '0.6rem',
    cursor: 'pointer',
    fontWeight: 'bold',
  },
  props: {
    variant: {
      outlined: {
        backgroundColor: 'transparent',
        color: 'green',
        border: 'solid 1px green',
      },
      contained: {
        backgroundColor: 'green',
        color: 'white',
        border: 'none',
      }
    },
  },
});

export default function Page() {
  return (
    <Wrapper>
      <Button
        variant={{
          xs: 'contained',
          lg: 'outlined',
        }}
      >
        Click
      </Button>
    </Wrapper>
  )
}

output:

Note that the responsive values here are determined by the breakpoints in your theme. Breakpoints in the theme system use media queries in css. If you want to customize these media queries, you can update the breakpoints values in your theme according to yourself.

For more information about the theme, check here.

Extending Elements

You can reuse a previously created element by wrapping it with createElement and create a new element that uses the properties of that element. This method will pass the element properties to the new element and allow you to add new properties to it.

In some cases you may want to change the html tag of an element with the same properties. In this case you can use the as property.

Defaults Attributes / Props

You can use the 'defaults' value when you want to define default attributes for the elements you create.

You can also use this feature for style props that you define yourself:

import { createElement } from '@tiger-ui/react'

const Container = createElement('div')({
  style: {
    padding: '6rem',
  },
});

interface InputProps {
  size?: 'small' | 'medium'
}

const Input = createElement('input')<InputProps>({
  style: {
    backgroundColor: 'green',
    border: '1px solid white',
    borderRadius: '5px',
    color: 'white',
    '::placeholder': {
      color: 'white',
    },
  },
  props: {
    size: {
      small: {
        padding: '0.5rem',
      },
      medium: {
        padding: '0.8rem',
      },
    },
  },
  defaults: {
    element: {
      type: 'password',
    },
    custom: {
      size: 'medium',
    },
  },
});

export default function Page() {
  return (
    <Container>
      <Input placeholder="default input" cssx={{ marginRight: '1rem' }} />
      <Input placeholder="small input" size="small" />
    </Container>
  )
}

output:

Children Content

You can add a children content inside the elements you created. This children content will import all the props and attributes used in your element as in a React Component Props. This feature allows the element you create to have a more flexible UI structure.

import { createElement } from '@tiger-ui/react'

const Container = createElement('div')({
  style: {
    padding: '6rem',
  },
});

interface LinkProps {
  color?: string;
}

const Link = createElement('a')<LinkProps>({
  style: {
    backgroundColor: 'green',
    padding: '0.5rem',
    borderRadius: '5px',
  },
  props: {
    color: (propValue) => ({
      color: propValue,
    }),
  },
  Children: ({ href, color }) => {
    return (
      <span>
        Link: {href} - Color: {color}
      </span>
    );
  },  
});

export default function Page() {
  return (
    <Container>
      <Link href="/home" color="white" />
    </Container>
  )
}

output:

html output:

Theming

Tiger UI React library provides you with a theme structure and you can update this theme according to your own wishes. This theme structure allows you to style your UI components in a more organized way. This method is not mandatory because Tiger UI provides you with a default theme. However, you may want to customize it according to your own corporate identity or for any other reason.

Create Theme

To create a customizable theme, you must first create a theme with TigerTheme and wrap your application with ThemeProvider.

/lib/ThemeRegistery.tsx

'use client'

import { ThemeProvider, TigerTheme } from "@tiger-ui/react";

const theme = new TigerTheme({
    themeName: 'my-theme',
    colors: {
      base: {
        primary: {
          main: '#26dbb0',
        },
      },
      background: {
        default: '#1c1c1c',
      }
    },
});

export default function ThemeRegistery({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      theme={theme}
      globalStyle={{
        'body': {
          backgroundColor: theme.colors.background.default,
          fontFamily: '"Poppins", sans-serif',
          margin: 0,
        },
      }}
    >
      {children}
    </ThemeProvider>
  );
}

You can also define a global style in this theme wrapper.

The next step is to wrap your app with the theme component you created.

/app/layout.tsx (Next JS App)

import { Metadata } from "next";

import ThemeRegistery from "../lib/ThemeRegistery";

export const metadata: Metadata = {
 title: "Tiger UI - Next JS App",
 description: "Tiger UI Next JS App",
};

export default function RootLayout({
 children,
}: {
 children: React.ReactNode;
}): JSX.Element {
 return (
   <html lang="en">
     <head>
       <link rel="preconnect" href="https://fonts.googleapis.com" />
       <link rel="preconnect" href="https://fonts.gstatic.com" />
       <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700;800;900&display=swap" rel="stylesheet" />
     </head>
     <body>
       <ThemeRegistery>
         {children}
       </ThemeRegistery>
     </body>
   </html>
 );
}

Default Theme Options

Even if you do not create a theme, there is a predefined theme by default.

You can review the default theme here:

Color System

You may also need to use dark, light and contrast colors of the colors you will use in the theme from time to time. Especially when developing a design system, for example, you may want a button you have created to take on a darker color when hovered over.

When you create your theme, the dark, light and contrast colors of all the main colors you add to colors.base are created automatically. You can customize these colors yourself if you wish.

const theme = new TigerTheme({
  themeName: 'my-theme',
  colors: {
    base: {
      primary: {
        main: '#26dbb0',
        contrast: '#000000',
        dark: '#22cfa7',
        light: '#33ddb5',
      },
      secondary: {
        main: '#27d86e',
        contrast: '#000000',
        dark: '#25cb67',
        light: '#34da77',
      },
    },
  },
});

You can follow a path like below to use the colors in the theme you created:

output:

Also, when defining your colors, if you want other color types to be created by default, just define the main color:

console output:

We have also provided some options that allow you to customize the dark, light and contrast values of the colors. For example, you can adjust the darkness of your dark color. Or if your contrast color is close to white, you can also customize this white color.

You can use the links below to learn more about @tiger-ui/color-palette-generator and @tiger-ui/contrast-color:

• @tiger-ui/color-palette-generator
• @tiger-ui/contrast-color

output:

Typescript - Theme Type Declaration

When creating a theme, you may want to consider adding your own values in addition to the default values.

If you are working in a typescript project, to add your own values you need to declare it to the default theme.

The following section contains the type values of the default theme. You can update the theme key you want to update in your project according to the type values here:

import type { RequiredKeyOnly } from '@tiger-ui/utils'
import type { Breakpoints, BreakpointsOptions } from './createBreakpoints'

// --- SHADOW --- //
export interface ShadowsValues {
  none: string;
  xs: string;
  sm: string;
  md: string;
  lg: string;
  xl: string;
};

export interface Shadows {
  values: ShadowsValues;
};

// --- COLORS --- //
// - Common Colors
export interface CommonColors {
  black: string;
  white: string;
};

// - Grey Colors
export interface GreyColors {
  50: string;
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
};

// - Text Colors 
export interface TextColors {
  primary: string;
  secondary: string;
  disabled: string;
};

// - Background Colors
export interface BackgroundColors {
  default: string;
  layer: string;
};

// - Actions Colors
export interface ActionsColors {
  disabled: string;
  disabledBackground: string;
}

// - Base Colors
export interface BaseColorsTypes {
  main: string;
  dark: string;
  light: string;
  contrast: string;
}
export interface BaseColors {
  primary: BaseColorsTypes;
  secondary: BaseColorsTypes;
  error: BaseColorsTypes;
  warning: BaseColorsTypes;
  info: BaseColorsTypes;
}

// --- RADIUS --- //
// - Values
export interface RadiusValues {
  none: string;
  xs: string;
  sm: string;
  md: string;
  lg: string;
  xl: string;
  xxl: string;
  full: string;
};

export interface Radius {
  values: RadiusValues;
}

// --- FONTS --- //
export interface Fonts {
  [key: string]: string;
}

// --- OPACITIES --- //
// - Values
export interface OpacitiesValues {
  hidden: number;
  xs: number;
  sm: number;
  md: number;
  lg: number;
  xl: number;
  visible: number;
  disabled: number;
}

export interface Opacities {
  values: OpacitiesValues;
}

// --- TYPOGRAPHY --- //
export type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'paragraph';
export type TypographiesVariants = Record<
  TypographyVariant,
  {
    fontSize: string;
    fontWeight: number;
    lineHeight: number;
  }
>

export interface Typographies extends TypographiesVariants {}

// --- TRANSITIONS --- //
// - Durations
export interface TransitionsDurations {
  slow: string;
  mid: string;
  fast: string;
}

// - Easing
export interface TransitionsEasing {
  easeInOut: string;
  easeOut: string;
  easeIn: string;
  ease: string;
  moment: string;
}

export interface Transitions {
  duration: TransitionsDurations;
  easing: TransitionsEasing;
}

// --- THEME --- //
export interface Theme {
  themeName: string;
  shadows: Shadows;
  breakpoints: Breakpoints;
  colors: {
    common: CommonColors;
    grey: GreyColors;
    text: TextColors;
    divider: string;
    background: BackgroundColors;
    actions: ActionsColors;
    base: BaseColors;
  };
  radius: Radius;
  fonts: Fonts;
  opacities: Opacities;
  typography: Typographies;
  transitions: Transitions;
};

/**
 * Theme values entered by the user.
*/
export interface ThemeOptions {
  themeName?: string;
  shadows?: Shadows;
  breakpoints?: BreakpointsOptions;
  colors?: Partial<{
    common: Partial<CommonColors>;
    grey: Partial<GreyColors>;
    text: Partial<TextColors>;
    divider: string;
    background: Partial<BackgroundColors>;
    actions: Partial<ActionsColors>;
    base:
      Partial<Record<keyof BaseColors, RequiredKeyOnly<Partial<BaseColorsTypes>, 'main'>>>
      | Record<string, RequiredKeyOnly<Partial<BaseColorsTypes>, 'main'>>;
  }>;
  radius?: Radius;
  fonts?: Fonts;
  opacities?: Opacities;
  typography?: Typographies;
  transitions?: Transitions;
}

For example, let's add our own custom color to the base colors in our project:

tiger-ui.d.ts

import '@tiger-ui/react';

import { BaseColorsTypes } from '@tiger-ui/react';

declare module '@tiger-ui/react' {
  export interface BaseColors {
    apple: BaseColorsTypes;
  }
}

Now, when creating a theme, we can add our own color accordingly to the type control.

import { ThemeProvider, TigerTheme } from "@tiger-ui/react";

const theme = TigerTheme({
    themeName: 'my-theme',
    colors: {
      base: {
        primary: {
          main: '#26dbb0',
        },
        apple: {
          main: '#f02416'
        },
      },
      background: {
        default: '#1c1c1c',
      }
    },
});

export default function ThemeRegistery({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      theme={theme}
      globalStyle={{
        'body': {
          backgroundColor: theme.colors.background.default,
          fontFamily: '"Poppins", sans-serif',
          margin: 0,
        },
      }}
    >
      {children}
    </ThemeProvider>
  );
}

CSSX / Custom Styling

Every element you create comes with a cssx prop defined by default. This prop allows you to quickly define css definitions on the JSX element.

This style object also supports css properties like :hover, :focus, :disabled, :active.

You can also access the current theme values with a parameter by giving a callback value.

import { createElement } from '@tiger-ui/react'

const Container = createElement('div')({
  style: {
    padding: '6rem',
  },
});

const Div = createElement('div')({});

export default function Page() {
  return (
    <Container>
      <Div
        cssx={(theme) => ({
          backgroundColor: theme.colors.base.primary.main,
          fontSize: theme.typography.h5.fontSize,
          borderRadius: theme.radius.values.md,
          padding: '0.7rem 1rem',
        })}
      >
        Hello World
      </Div>
    </Container>
  )
}

output: