How to Use Clay

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

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

npm install @clayui/css @clayui/{PACKAGE_NAME}

Yarn

yarn add @clayui/css @clayui/{PACKAGE_NAME}

Important Note: Be Mindful of the Asterisk: When using the @clayui/* command for installation, it's crucial to remember that the asterisk (*) is a placeholder. It's not a valid package name on its own. To install a specific Clay package, you must replace the asterisk with the name of the package you require.

For instance, if you want to install the "Clay Button" package, the correct command would be:

Copied!

Code Sample (expand to see it)

npm install @clayui/button or yarn add @clayui/button

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.

<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:

- 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

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.

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

import {ClayCheckbox, ClayRadio} from '@clayui/form';
import ClayButton from '@clayui/button';
import ClayDropDown from '@clayui/drop-down';

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.

const [expand, setExpand] = useState(false);

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

<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:

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

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

import ClayDropDown, {ClayDropDownWithItems} from '@clayui/drop-down';

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