# 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.
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.