LeafyGreen UI

A library of React components, CSS patterns, and CLI tools for MongoDB’s LeafyGreen Design System.

License

Getting Started

With LeafyGreen CLI

Create or open a React project
Install the LeafyGreen CLI

npm install -g @lg-tools/cli

Install all, or some LeafyGreen components

lg install

lg install button combobox

Import LeafyGreen components into your project

import Button from '@leafygreen-ui/button';
import { Combobox, ComboboxOptions } from '@leafygreen-ui/combobox';

Without CLI

Create or open a React project
Install individual LeafyGreen components using npm, pnpm, or yarn

pnpm add @leafygreen-ui/button

Import LeafyGreen components into your project

import Button from '@leafygreen-ui/button';

Packages

Package	Downloads	Live Example
@leafygreen-ui/a11y	@leafygreen-ui/a11y?color=white" alt="downloads">	Live Example
@leafygreen-ui/avatar	@leafygreen-ui/avatar?color=white" alt="downloads">	Live Example
@leafygreen-ui/badge	@leafygreen-ui/badge?color=white" alt="downloads">	Live Example
@leafygreen-ui/banner	@leafygreen-ui/banner?color=white" alt="downloads">	Live Example
@leafygreen-ui/box	@leafygreen-ui/box?color=white" alt="downloads">	Live Example
@leafygreen-ui/button	@leafygreen-ui/button?color=white" alt="downloads">	Live Example
@leafygreen-ui/callout	@leafygreen-ui/callout?color=white" alt="downloads">	Live Example
@leafygreen-ui/card	@leafygreen-ui/card?color=white" alt="downloads">	Live Example
@leafygreen-ui/checkbox	@leafygreen-ui/checkbox?color=white" alt="downloads">	Live Example
@leafygreen-ui/chip	@leafygreen-ui/chip?color=white" alt="downloads">	Live Example
@leafygreen-ui/code	@leafygreen-ui/code?color=white" alt="downloads">	Live Example
@leafygreen-ui/combobox	@leafygreen-ui/combobox?color=white" alt="downloads">	Live Example
@leafygreen-ui/confirmation-modal	@leafygreen-ui/confirmation-modal?color=white" alt="downloads">	Live Example
@leafygreen-ui/copyable	@leafygreen-ui/copyable?color=white" alt="downloads">	Live Example
@leafygreen-ui/date-picker	@leafygreen-ui/date-picker?color=white" alt="downloads">	Live Example
@leafygreen-ui/date-utils	@leafygreen-ui/date-utils?color=white" alt="downloads">	Live Example
@leafygreen-ui/descendants	@leafygreen-ui/descendants?color=white" alt="downloads">	Live Example
@leafygreen-ui/drawer	@leafygreen-ui/drawer?color=white" alt="downloads">	Live Example
@leafygreen-ui/emotion	@leafygreen-ui/emotion?color=white" alt="downloads">	Live Example
@leafygreen-ui/empty-state	@leafygreen-ui/empty-state?color=white" alt="downloads">	Live Example
@leafygreen-ui/expandable-card	@leafygreen-ui/expandable-card?color=white" alt="downloads">	Live Example
@leafygreen-ui/form-field	@leafygreen-ui/form-field?color=white" alt="downloads">	Live Example
@leafygreen-ui/form-footer	@leafygreen-ui/form-footer?color=white" alt="downloads">	Live Example
@leafygreen-ui/gallery-indicator	@leafygreen-ui/gallery-indicator?color=white" alt="downloads">	Live Example
@leafygreen-ui/guide-cue	@leafygreen-ui/guide-cue?color=white" alt="downloads">	Live Example
@leafygreen-ui/hooks	@leafygreen-ui/hooks?color=white" alt="downloads">	Live Example
@leafygreen-ui/icon	@leafygreen-ui/icon?color=white" alt="downloads">	Live Example
@leafygreen-ui/icon-button	@leafygreen-ui/icon-button?color=white" alt="downloads">	Live Example
@leafygreen-ui/info-sprinkle	@leafygreen-ui/info-sprinkle?color=white" alt="downloads">	Live Example
@leafygreen-ui/inline-definition	@leafygreen-ui/inline-definition?color=white" alt="downloads">	Live Example
@leafygreen-ui/input-option	@leafygreen-ui/input-option?color=white" alt="downloads">	Live Example
@leafygreen-ui/leafygreen-provider	@leafygreen-ui/leafygreen-provider?color=white" alt="downloads">	Live Example
@leafygreen-ui/lib	@leafygreen-ui/lib?color=white" alt="downloads">	Live Example
@leafygreen-ui/loading-indicator	@leafygreen-ui/loading-indicator?color=white" alt="downloads">	Live Example
@leafygreen-ui/logo	@leafygreen-ui/logo?color=white" alt="downloads">	Live Example
@leafygreen-ui/marketing-modal	@leafygreen-ui/marketing-modal?color=white" alt="downloads">	Live Example
@leafygreen-ui/menu	@leafygreen-ui/menu?color=white" alt="downloads">	Live Example
@leafygreen-ui/modal	@leafygreen-ui/modal?color=white" alt="downloads">	Live Example
@leafygreen-ui/number-input	@leafygreen-ui/number-input?color=white" alt="downloads">	Live Example
@leafygreen-ui/ordered-list	@leafygreen-ui/ordered-list?color=white" alt="downloads">	Live Example
@leafygreen-ui/pagination	@leafygreen-ui/pagination?color=white" alt="downloads">	Live Example
@leafygreen-ui/palette	@leafygreen-ui/palette?color=white" alt="downloads">	Live Example
@leafygreen-ui/password-input	@leafygreen-ui/password-input?color=white" alt="downloads">	Live Example
@leafygreen-ui/pipeline	@leafygreen-ui/pipeline?color=white" alt="downloads">	Live Example
@leafygreen-ui/polymorphic	@leafygreen-ui/polymorphic?color=white" alt="downloads">	Live Example
@leafygreen-ui/popover	@leafygreen-ui/popover?color=white" alt="downloads">	Live Example
@leafygreen-ui/portal	@leafygreen-ui/portal?color=white" alt="downloads">	Live Example
@leafygreen-ui/radio-box-group	@leafygreen-ui/radio-box-group?color=white" alt="downloads">	Live Example
@leafygreen-ui/radio-group	@leafygreen-ui/radio-group?color=white" alt="downloads">	Live Example
@leafygreen-ui/ripple	@leafygreen-ui/ripple?color=white" alt="downloads">	Live Example
@leafygreen-ui/search-input	@leafygreen-ui/search-input?color=white" alt="downloads">	Live Example
@leafygreen-ui/segmented-control	@leafygreen-ui/segmented-control?color=white" alt="downloads">	Live Example
@leafygreen-ui/select	@leafygreen-ui/select?color=white" alt="downloads">	Live Example
@leafygreen-ui/side-nav	@leafygreen-ui/side-nav?color=white" alt="downloads">	Live Example
@leafygreen-ui/skeleton-loader	@leafygreen-ui/skeleton-loader?color=white" alt="downloads">	Live Example
@leafygreen-ui/split-button	@leafygreen-ui/split-button?color=white" alt="downloads">	Live Example
@leafygreen-ui/stepper	@leafygreen-ui/stepper?color=white" alt="downloads">	Live Example
@leafygreen-ui/table	@leafygreen-ui/table?color=white" alt="downloads">	Live Example
@leafygreen-ui/tabs	@leafygreen-ui/tabs?color=white" alt="downloads">	Live Example
@leafygreen-ui/testing-lib	@leafygreen-ui/testing-lib?color=white" alt="downloads">	Live Example
@leafygreen-ui/text-area	@leafygreen-ui/text-area?color=white" alt="downloads">	Live Example
@leafygreen-ui/text-input	@leafygreen-ui/text-input?color=white" alt="downloads">	Live Example
@leafygreen-ui/toast	@leafygreen-ui/toast?color=white" alt="downloads">	Live Example
@leafygreen-ui/toggle	@leafygreen-ui/toggle?color=white" alt="downloads">	Live Example
@leafygreen-ui/tokens	@leafygreen-ui/tokens?color=white" alt="downloads">	Live Example
@leafygreen-ui/tooltip	@leafygreen-ui/tooltip?color=white" alt="downloads">	Live Example
@leafygreen-ui/typography	@leafygreen-ui/typography?color=white" alt="downloads">	Live Example
@lg-charts/chart-card	@lg-charts/chart-card?color=white" alt="downloads">	Live Example
@lg-charts/colors	@lg-charts/colors?color=white" alt="downloads">	Live Example
@lg-charts/core	@lg-charts/core?color=white" alt="downloads">	Live Example
@lg-charts/drag-provider	@lg-charts/drag-provider?color=white" alt="downloads">	Live Example
@lg-charts/legend	@lg-charts/legend?color=white" alt="downloads">	Live Example
@lg-charts/series-provider	@lg-charts/series-provider?color=white" alt="downloads">	Live Example
@lg-chat/avatar	@lg-chat/avatar?color=white" alt="downloads">	Live Example
@lg-chat/chat-disclaimer	@lg-chat/chat-disclaimer?color=white" alt="downloads">	Live Example
@lg-chat/chat-window	@lg-chat/chat-window?color=white" alt="downloads">	Live Example
@lg-chat/fixed-chat-window	@lg-chat/fixed-chat-window?color=white" alt="downloads">	Live Example
@lg-chat/input-bar	@lg-chat/input-bar?color=white" alt="downloads">	Live Example
@lg-chat/leafygreen-chat-provider	@lg-chat/leafygreen-chat-provider?color=white" alt="downloads">	Live Example
@lg-chat/lg-markdown	@lg-chat/lg-markdown?color=white" alt="downloads">	Live Example
@lg-chat/message	@lg-chat/message?color=white" alt="downloads">	Live Example
@lg-chat/message-feed	@lg-chat/message-feed?color=white" alt="downloads">	Live Example
@lg-chat/message-feedback	@lg-chat/message-feedback?color=white" alt="downloads">	Live Example
@lg-chat/message-prompts	@lg-chat/message-prompts?color=white" alt="downloads">	Live Example
@lg-chat/message-rating	@lg-chat/message-rating?color=white" alt="downloads">	Live Example
@lg-chat/rich-links	@lg-chat/rich-links?color=white" alt="downloads">	Live Example
@lg-chat/title-bar	@lg-chat/title-bar?color=white" alt="downloads">	Live Example
@lg-tools/build	@lg-tools/build?color=white" alt="downloads">
@lg-tools/cli	@lg-tools/cli?color=white" alt="downloads">
@lg-tools/codemods	@lg-tools/codemods?color=white" alt="downloads">
@lg-tools/create	@lg-tools/create?color=white" alt="downloads">
@lg-tools/install	@lg-tools/install?color=white" alt="downloads">
@lg-tools/link	@lg-tools/link?color=white" alt="downloads">
@lg-tools/lint	@lg-tools/lint?color=white" alt="downloads">
@lg-tools/meta	@lg-tools/meta?color=white" alt="downloads">
@lg-tools/slackbot	@lg-tools/slackbot?color=white" alt="downloads">
@lg-tools/storybook-addon	@lg-tools/storybook-addon?color=white" alt="downloads">
@lg-tools/storybook-decorators	@lg-tools/storybook-decorators?color=white" alt="downloads">
@lg-tools/storybook-utils	@lg-tools/storybook-utils?color=white" alt="downloads">
@lg-tools/test	@lg-tools/test?color=white" alt="downloads">
@lg-tools/test-harnesses	@lg-tools/test-harnesses?color=white" alt="downloads">
@lg-tools/update	@lg-tools/update?color=white" alt="downloads">
@lg-tools/validate	@lg-tools/validate?color=white" alt="downloads">

Development

Setup

Node >= 18.0.0 required.

via homebrew with brew install node

via nodejs installer
Install PNPM >= 9.15.0.

PNPM Installation documentation

Clone the repository.

# Navigate to the directory you'd like to clone the repository into
$ cd ~/my/repositories
# Clone the repository.
# We recommend installing using the SSH address rather than the HTTPS one to make authentication easier for you. To set up SSH authentication with GitHub, see their guide: https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account

Install dependencies and link packages.
```
pnpm run init
```

Storybook

Start up storybook to see all UI components that exist:

pnpm start

Note: Running storybook doesn’t trigger changes in dependencies, only the main component’s — e.g. If you’re looking at Button, and make a change to Lib, you need to rebuild Lib for Storybook to see those changes in Button.

Building Packages

To rebuild all packages:

pnpm build

To rebuild select packages, filter using --filter:

pnpm build --filter="[package]"
// ex. --filter="@leafygreen-ui/hooks"

Development within an Application

To actively develop leafygreen-ui components within an application, the following script will link all leafygreen-ui components within your application to the local leafygreen-ui repository.

This will allow you to make changes to your local repository of leafygreen-ui and see those changes immediately reflected within your running application. This allows you to develop both in isolation (within leafygreen-ui) and in the context of your application.

To do this, clone this repository and navigate to the root directory (where package.json is located), then run the following:

pnpm run link -- ${PATH_TO_APPLICATION}

The script does several things in order:

This builds every leafygreen-ui component so they are ready to be linked
It scans your application for any installed leafygreen-ui components in your node_modules/@leafygreen-ui folder.
NOTE: If the package is new and unpublished/not installed, you will need to create a directory for the new component within your application inside node_modules/@leafygreen-ui before running this command.
If any leafygreen-ui components are found then the script uses pnpm link to link every node_modules/@leafygreen-ui module to your local leafygreen-ui repository.

After the script completes, you can make changes directly to the component in your local leafygreen-ui repository. Once you do this, run pnpm build in the root of the leafygreen-ui repository and the changes will be visible on your running application.

Creating New Component

Getting Started

To get started quickly and easily run pnpm create-package my-new-package. When you run this command, we create a directory containing all of the boilerplate code that you’ll need to start developing your new Component.

Note: it’s important to follow the kebab-casing convention described above.

Add the new component to build.tsconfig.json
If you are using any leafygreen-ui dependencies in your new component, add the dependency to the component directory’s tsconfig.json.
Run pnpm run init to link all packages before starting development

Formatting and linting

When you run pnpm fix, we do the following:

We run pnpm prettier:fix so that we have consistently formatted code.
We run pnpm eslint:fix to catch any syntax errors, unused variables, and any other easy-to-catch issues.

To fix all files in the repository, run the following:

pnpm fix

To check if any files need formatting without automatically formatting them, run the following:

pnpm prettier:check

To run linting without automatically fixing issues, run the following:

pnpm eslint:check

Typechecking

To run typechecking without compiling the code, run the following:

pnpm ts

Testing

To run the unit tests for our components, run the following:

pnpm test

Committing

When making a PR that contains changes that should be included in a package’s changelog, be sure to do so by running:

pnpm changeset

This will generate a changes.json file, keeping track of version upgrades and update descriptions. We follow semver conventions for versioning, so each change will either be major, minor, or patch.

Make sure that the PR includes the changes made by running this command.

Publishing

Merge the automatically generated Version Packages PR that will contain appropriate version bumps and changelog documentation.
Push the tags from the release up to Github.

git push --follow-tags

Publishing Pre-releases

Read more in-depth pre-release guides here

Pre-releases let you publish an alpha/beta/next version of a component, allowing developers to test a component before fully releasing a component.

Let’s imagine we want to publish a beta release of some component. Our work is being done on a branch called new-feature

Create a new branch off your component branch git checkout -b pre-release
- this makes sure your package updates stay independent
Enter pre-release mode: pnpm changeset pre enter beta (name can be next, beta, alpha, or any other name)
Update package versions pnpm changeset version
- This will update any packages with existing changeset files to version X.Y.Z-beta.0 (or whatever name you used)
Commit these updates git commit -am "Prerelease version packages"
Build the component(s) you’re pre-releasing pnpm build <...components>
Publish the prerelease with pnpm changeset publish

Any new work you do should be done in the original (new-feature) branch.
To publish a new pre-release version, pull the changes from new-feature into branch pre-release, and follow steps 3-5.

When new-feature is merged into main, you can safely delete the pre-release branch

Deploy gh-pages

You can deploy a static build of our Storybook site to gh-pages from the main branch.

First be sure you’ve built a static version of Storybook with the script: build-storybook
Then deploy to gh-pages: pnpm release:site

To deploy to your own mirror of leafygreen-ui

Run pnpm demo:site [your_github_username].
If you haven’t built a static version of Storybook yet, you will be prompted to do so.
You will be asked for confirmation before Storybook is published.

License

The source files in this repository are made available under the terms of the Apache License, version 2.0.