# Overview

Freshworks Crayons is a library of UI components that are the building blocks to help create an intuitive and uniform user interface for all your apps. Crayons helps developers build apps that adhere to the UX standards set by the Freshworks Design System.

# Features

Tiny, highly optimized 30+ web components built with Stencil (opens new window)
No build or compiling required
Simply add the static files to any project
Tree shakable bundle for components
Lazy-loaded components without configuration
Style customisation through CSS Variables
Framework Wrappers for React (opens new window)
Set of CSS utilities (opens new window) to speed up development
i18n (opens new window) support
icon library (opens new window) with support for using external icons

# Installation

You can install a specific version of Crayons using crayons@v[version]

# Getting Started

# Usage via CDN

From your app’s root html file add the following scripts:

<script
  type="module"
  src="https://unpkg.com/@freshworks/crayons@v3/dist/crayons/crayons.esm.js"
></script>
<script
  nomodule
  src="https://unpkg.com/@freshworks/crayons@v3/dist/crayons/crayons.js"
></script>

You can now use the Crayons components just like how you would use any other html element.

Get Started

Show Code

You can use UNPKG (opens new window) to query specific versions in your app.

# Usage via Node Modules

Install the package

  npm install @freshworks/crayons@v3 --save

Put a script tag similar to this

<script src="node_modules/@freshworks/crayons/dist/crayons.js"></script>

in the head of your index.html

Now you can use the element anywhere in your template, JSX, html etc.

# Framework Bindings

The @freshworks/crayons package can be used in simple HTML, or by vanilla JavaScript without any framework at all. Crayons v3 introduces framework bindings that make it easier to integrate Crayons into a framework such as React. (However, at the lowest-level framework bindings are still just using Crayons core and Web Components).

To use React wrapper use below:

import { FwButton } from '@freshworks/crayons/react';

For more information please check here (opens new window)

# Adding CSS Utils

Crayons v3 also provides a set of CSS utilities to help with application development. You can use these utils by adding 'crayons-min.css' file in your app.

# Usage via Node Modules

<link
  rel="stylesheet"
  href="node_modules/@freshworks/crayons/css/crayons-min.css"
/>

# Usage via CDN

<link
  rel="stylesheet"
  href="https://unpkg.com/@freshworks/crayons@v3/css/crayons-min.css"
/>

Note: CSS utils are optional. Crayons can be used without including crayons-min.css.

# Why Web Components?

All the crayons components are built as web compponents.

Web components provides a way to create our own HTML elements and use them in any framework.

With every growing popularity of frameworks such as React, Vue, Angular component driven development has become a need. Components help us encapsulate styles and behaviors into reusable blocks.

Drawbacks with Framework specific components:

The components can only be used in their specific framework.
Any new framework or version changes can lead to breaking changes and require substantial effort to update the components.
Web components solve these problems.
- They're supported by all modern browsers.
- They're framework agnostic.
- They're a part of the web standard.

Migrating to v3 →