Skip to main contentSkip to search
Clay
  • Get Started
    • How to Use Clay
    • How to Read This Documentation
    • Composition Philosophy
    • Migrating From v2.x
    • Using Clay in JSPs
  • Components
    • Alert
    • Application Bar
    • Aspect Ratio
    • Autocomplete
    • Badge
    • Breadcrumb
    • Button Group
    • Buttons
    • Card
    • Chart
    • Color Picker
    • Data Provider
    • Date Picker
    • DropDown
    • Empty State
    • Form
      • Checkbox
      • Dual List Box
      • Input
      • Radio Group
      • Select
      • Select Box
      • Toggle Switch
    • Forms Hierarchy
    • Heading
    • Icon
    • Label
    • Layout
    • Link
    • List
    • Loading Indicator
    • Localized Input
    • Management Toolbar
    • Modal
    • Multi Select
    • Multi Step Nav
    • Nav
    • Navigation Bar
    • OverlayMask
    • Pagination
    • Pagination Bar
    • Panel
    • Picker
    • Popover
    • Progress Bar
    • Provider
    • Sidebar
    • Slider
    • Sticker
    • Table
    • Tabs
    • Text
    • Timelines
    • Time Picker
    • Toolbar
    • Tooltip
    • TreeView
    • Upper Toolbar
    • VerticalBar
    • Vertical Navigation
  • Contributing
  • CSS Framework
    • Paver
    • SCSS
    • Color
    • Grid
    • Content
      • Typography
      • C Kbd
    • Utilities
      • Accessibility
      • Autofit
      • Border
      • C Focus Inset
      • C Inner
      • Color Utilities
      • C Spacing Utilities
      • Display
      • Flex
      • Float
      • Inline Item
      • Overflow
      • Position
      • Shadow
      • Text
      • Vertical Align
      • Visibility
      • Width and Height
    • Playground
  • Examples
K
  • Docs
  • Sass API
  • Blog
  • Storybook
  • Codesandbox
  • Github
  • Use this menu to toggle between Atlas and Base Themes.

How to Use Clay

Practical guidelines to start using Clay, a quick guide on how to install components and css to get started.

  • Install with NPM or Yarn
    • NPM
    • Yarn
  • Install via Clay CSS CDN
  • Quick start

Clay follows some fundamentals and we recommend that you read more about this before you start using it in your application.

  • Composing

Install with NPM or Yarn

Clay makes the components and CSS available in its own @clayui scope, for example the card package is available through @clayui/card and the css is available through @clayui/css. In some packages we expose multiple components, for example the @clayui/form package contains components Checkbox, Radio, Input, Select...

You can check out the full list of packages available in NPM.

NPM

Copied!
Code Sample (expand to see it)
npm install @clayui/css @clayui/*

Yarn

Copied!
Code Sample (expand to see it)
yarn add @clayui/css @clayui/*

Install via Clay CSS CDN

We provide Clay CSS via CDN, which is an option when you do not want to install the clay package via NPM or Yarn.

Copied!
Code Sample (expand to see it)
<link
	rel="stylesheet"
	href="https://cdn.jsdelivr.net/npm/@clayui/css/lib/css/atlas.css"
/>

If you want a specific version of CSS, specify the desired version.

Example:

Copied!
Code Sample (expand to see it)
- https://cdn.jsdelivr.net/npm/@clayui/css/lib/css/atlas.css
+ https://cdn.jsdelivr.net/npm/@clayui/css@3.0.0/lib/css/atlas.css

Quick start

Warning Before you get started with this quick start, read about Clay's fundamentals of composition to move on. The information below is assuming you have read about Clay's compositional philosophy and learned about the terms.
Warning This quick start requires that you have a minimum knowledge of React Hooks, not much of your API's will be used but just useState to control the component.

For this quick start we will use codesandbox which does not need to install an environment on your machine.

Use the codesandbox below as your text editor and environment so we can follow through with the examples.

Let's use the DropDown component (@clayui/drop-down) and understand how the compositing philosophy works for this component so you can start replicating on other components.

Info You can check the ClayDropDown package documentation for its API and usage philosophy.

Before we get started, let's import the main packages that we will use to create a low-level Drop Down with Clay components.

Copied!
Code Sample (expand to see it)
import {ClayCheckbox, ClayRadio} from '@clayui/form';
import ClayButton from '@clayui/button';
import ClayDropDown from '@clayui/drop-down';
Info These packages are installed in the sandbox environment, so feel free to fork the environment if you want to test with other Clay components.

As you learned from Clay's compositional philosophy, we are using a low-level DropDown component, as its essence is a controlled component and for that you need to control DropDown's expand state. Let's use React's useState to control the state.

Copied!
Code Sample (expand to see it)
const [expand, setExpand] = useState(false);

Soon after we can add the components to see rendered on the screen.

Copied!
Code Sample (expand to see it)
<ClayDropDown
	active={expand}
	onActiveChange={setExpand}
	trigger={<ClayButton>{'Click Me'}</ClayButton>}
/>

At first we are seeing only ClayButton being rendered with empty DropDown, as it is a low-level component we need to compose DropDown content with other components to see a list of actions or add whatever you want inside.

Try this:

Copied!
Code Sample (expand to see it)
<ClayDropDown
	active={expand}
	onActiveChange={setExpand}
	trigger={<ClayButton>{'Click Me'}</ClayButton>}
>
	<h1>Menu</h1>
</ClayDropDown>

Now we can compose with other Clay components and add a Checkbox and Radio to the content.

Copied!
Code Sample (expand to see it)
<ClayDropDown
	active={expand}
	onActiveChange={setExpand}
	trigger={<ClayButton>{'Click Me'}</ClayButton>}
>
	<ClayDropDown.ItemList>
		<ClayDropDown.Item href="#1">Linkable</ClayDropDown.Item>
		<ClayDropDown.Item>
			<ClayCheckbox checked label="Checkbox" onChange={() => {}} />
		</ClayDropDown.Item>
		<ClayDropDown.Item>
			<ClayRadio checked label="Radio" value="radio" />
		</ClayDropDown.Item>
	</ClayDropDown.ItemList>
</ClayDropDown>

Low-level components in Clay allow you to compose and add your own rules, allowing you to achieve your design standards that are tied to Lexicon fundamentals. A team that follows the Lexicon team's predicted behaviors and cases can use the high-level components that help you code faster.

See the same example above being reflected in a high-level component.

Copied!
Code Sample (expand to see it)
import ClayDropDown, {ClayDropDownWithItems} from '@clayui/drop-down';
Copied!
Code Sample (expand to see it)
<ClayDropDownWithItems
	items={[
		{
			href: '#linkable',
			label: 'linkable',
		},
		{
			checked: true,
			label: 'Checkbox',
			type: 'checkbox',
		},
		{
			label: 'Radio',
			type: 'radio',
			value: 'radio',
		},
	]}
	trigger={<ClayButton>{'Click Me'}</ClayButton>}
/>

If you had problems, this is the final sandbox with all the examples described above.

How can this be improved? Create an issue!