Skip to content

LeafyGreen UI – LeafyGreen's React UI Kit

License

Notifications You must be signed in to change notification settings

mongodb/leafygreen-ui

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

LeafyGreen UI

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

mongodb.design

Storybook

Release License

Getting Started

With LeafyGreen CLI

  1. Create or open a React project
  2. Install the LeafyGreen CLI
npm install -g @lg-tools/cli
  1. Install all, or some LeafyGreen components
lg install
lg install button combobox
  1. Import LeafyGreen components into your project
import Button from '@leafygreen-ui/button';
import { Combobox, ComboboxOptions } from '@leafygreen-ui/combobox';

Without CLI

  1. Create or open a React project
  2. Install individual LeafyGreen components using npm, pnpm, or yarn
pnpm add @leafygreen-ui/button
  1. Import LeafyGreen components into your project
import Button from '@leafygreen-ui/button';

Packages

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

Development

Setup

  1. Node >= 18.0.0 required.

    via homebrew with brew install node

    via nodejs installer

  2. Install PNPM >= 9.15.0.

    PNPM Installation documentation

  3. 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
  4. 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:

  1. This builds every leafygreen-ui component so they are ready to be linked

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

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

  1. Merge the automatically generated Version Packages PR that will contain appropriate version bumps and changelog documentation.

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

  1. Create a new branch off your component branch git checkout -b pre-release
    • this makes sure your package updates stay independent
  2. Enter pre-release mode: pnpm changeset pre enter beta (name can be next, beta, alpha, or any other name)
  3. 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)
  4. Commit these updates git commit -am "Prerelease version packages"
  5. Build the component(s) you're pre-releasing pnpm build <...components>
  6. 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.

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

To deploy to your own mirror of leafygreen-ui

  1. Run pnpm demo:site [your_github_username].
  2. If you haven't built a static version of Storybook yet, you will be prompted to do so.
  3. 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.