Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/trussworks/react-uswds

USWDS 3.0 components built in React
https://github.com/trussworks/react-uswds

component-library design-patterns design-system hacktoberfest react storybook truss uswds

Last synced: 1 day ago
JSON representation

USWDS 3.0 components built in React

Host: GitHub
URL: https://github.com/trussworks/react-uswds
Owner: trussworks
License: apache-2.0
Created: 2019-09-27T17:37:06.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2024-10-28T05:20:16.000Z (3 months ago)
Last Synced: 2024-10-31T13:23:50.682Z (3 months ago)
Topics: component-library, design-patterns, design-system, hacktoberfest, react, storybook, truss, uswds
Language: TypeScript
Homepage: https://trussworks.github.io/react-uswds/
Size: 34.2 MB
Stars: 186
Watchers: 8
Forks: 81
Open Issues: 87
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS

Awesome Lists containing this project

README

        # @trussworks/react-uswds

[![All Contributors](https://img.shields.io/badge/all_contributors-35-orange.svg?style=flat-square)](#contributors-)

[![npm version](https://img.shields.io/npm/v/@trussworks/react-uswds)](https://www.npmjs.com/package/@trussworks/react-uswds)

[![uswds version](https://img.shields.io/github/package-json/dependency-version/trussworks/react-uswds/dev/@uswds/uswds)](https://www.npmjs.com/package/@uswds/uswds)

[![npm downloads](https://img.shields.io/npm/dm/@trussworks/react-uswds)](https://www.npmjs.com/package/@trussworks/react-uswds)

**ReactUSWDS Component Library**

This is a frontend component library, built in [React](https://reactjs.org/) with [Typescript](https://www.typescriptlang.org/), based on design patterns defined by the [United States Web Design System (USWDS) 3.0](https://designsystem.digital.gov/). Our primary goal is to document and provide common UI components following the USWDS specification. This library removes a significant amount of overhead UI development for projects based on this standard.

A deployed instance of the ReactUSWDS Storybook is located at: [https://trussworks.github.io/react-uswds/](https://trussworks.github.io/react-uswds/)

**Table of Contents**

- [@trussworks/react-uswds](#trussworksreact-uswds)

  - [Install](#install)

  - [Peer Dependencies](#peer-dependencies)

  - [Usage](#usage)

    - [USWDS](#uswds)

    - [NodeJS](#nodejs)

    - [Pre-Release](#pre-release)

    - [Implementation examples](#implementation-examples)

  - [Background](#background)

    - [Non-Goals](#non-goals)

  - [Active Maintainers](#active-maintainers)

  - [Contributing](#contributing)

    - [Quick links:](#quick-links)

  - [License](#license)

  - [Contributors ✨](#contributors-)

## Install

Install this package with npm or yarn:

```

yarn add @trussworks/react-uswds

```

or

```

npm i @trussworks/react-uswds

```

## Peer Dependencies

This library relies on some [peer dependencies](./package.json). Please verify these peer dependencies were added to your project (if they did not already exist) after adding this library.

## Usage

### USWDS

It is strongly suggested applications use the same version of USWDS that was used to build the version of ReactUSWDS they're using (see this repo's uswds `devDependency` in [package.json](./package.json)).

A version mismatch may result in unexpected markup & CSS combinations.

For flexibility, ReactUSWDS will not trigger warnings if consumers choose to use a higher minor version of `uswds` (hence the careted uswds `peerDependency` in [package.json](./package.json)).

If encountering unexpected markup issues when choosing _not_ to use the matching `devDependency` version of `uswds`, consumers should check whether aligning the versions resolves their issue(s).

You can import ReactUSWDS components using ES6 syntax:

```

import { Alert } from '@trussworks/react-uswds'

```

> **Warning:** Do _not_ include USWDS JS in your project alongside this library (i.e., using `import 'uswds'`), as that will result in some components that use JS (such as the ComboBox) to initialize twice.

Also make sure to include the following in order to import the compiled CSS from this project:

```

@import '~@trussworks/react-uswds/lib/index.css';

```

If you aren't already using USWDS as a dependency, you also need to import USWDS styles. **[Read more info about using USWDS styles and assets here](./docs/styles_and_assets.md)**

Having issues? See [FAQs](./docs/faqs.md).

### NodeJS

We develop on this library with the version of node defined in [`.node-version`](.node-version). We run the test suite against the major released versions of node that are still in active LTS and not development releases. Specific versions are defined in the workflow: `.github/workflows/build-and-test.yml`. Those are the versions we expect to support, if you are using a pre-release or development version of node you may run into unexpected issues.

Having issues? See [FAQs](./docs/faqs.md).

### Pre-Release

See [prelease.md](docs/prerelease.md)

### Implementation examples

[We decided](https://github.com/trussworks/react-uswds/issues/2001) to focus on our [storybook](https://trussworks.github.io/react-uswds/) over hosting an example/boilerplate implementation, but you can find a few such things from our friends:

* [NASA's Americana Remix stack](https://github.com/nasa-gcn/americana-stack?tab=readme-ov-file)

* [USDS's Gatsby starter template](https://github.com/usds/gatsby-uswds-ts-starter)

* [Nava's Next.js starter template](https://github.com/navapbc/template-application-nextjs)

You can also check out some open source projects using React-USWDS across federal and state governments:

* DOL

  * [Unemployment Insurance Claimant Experience Pilot](https://github.com/USDepartmentofLabor/ui-claimant-experience-pilot)

  * [New Jersey's Unemployment Insurance Claimant Intake Pilot](https://github.com/USDepartmentofLabor/UI-Claimant-Experience-NJ-Pilot)

* USA.gov

  * [Vote.gov](https://vote.gov/)

  * [Search.gov](https://search.gov/)

* CDC

  * [ReportStream](https://github.com/CDCgov/prime-reportstream)

  * [EpiSync](https://github.com/CDCgov/EpiSync)

  * [National Electronic Disease Surveillance System Base System](https://github.com/CDCgov/NEDSS-Modernization)

* Centers for Medicare & Medicaid Services (CMS):

  * [EASi Application](https://github.com/CMSgov/easi-app)

  * [Model Innovation Tool (MINT)](https://github.com/CMSgov/mint-app)

* Others

  * [DoD and TRANSCOM's MilMove](https://github.com/transcom/mymove)

  * [OMB's Environment Justice Scorecard](https://github.com/usds/ej-scorecard)

  * [U.S. Office of Head Start's Training & Technical Assistance Smart Hub](https://github.com/HHS/Head-Start-TTADP)

  * [CISA's XFD application](https://github.com/cisagov/XFD)

  * ...and more on our [dependents page](https://github.com/trussworks/react-uswds/network/dependents)

## Background

The primary deliverable is a published npm package that can be included as a dependency in other projects that use USWDS with React. In order for these components to be useful, they should follow best practices for accessible, semantic, markup; be well-tested across browsers and devices; and allow for an appropriate level of customization. We adhere to a set of [development guidelines](./docs/contributing.md#guidelines) as much as possible and use automation to enforce tests, linting, and other standards.

### Non-Goals

This is not meant to be a one-size-fits-all front end solution, We are starting off with the opinionated decision to cater towards projects that use the U.S. Design System 2.0, and encapsulate these specific styles and markup in React components.

In the process, we expect to gain learnings around how to best abstract out UI code from implementation; how to better standardize and document front end code practices; and how to develop, maintain, and distribute a shared JS library in alignment with our [company values at Truss](https://truss.works/values).

## Active Maintainers

- [Courtney Eimerman-Wallace](https://github.com/crwallace)

We are starting to rotate Trussel maintainer responsibilities. Check out the [maintainers README](./docs/for_maintainers.md).

## Contributing

Interested in contributing? See our [guidelines and dev setup here](./docs/contributing.md).

Are you a Trussel and new to this project? Check out our [on & offboarding guide](./docs/for_trussels.md) made just for you!

This repository is governed by the [Contributor Covenant](./CODE_OF_CONDUCT.md)

### Quick links:

- [Yarn scripts](./docs/contributing.md#available-commands)

- [PR commit guidelines](./docs/contributing.md#opening--merging-pull-requests)

- [Adding new components](./docs/adding_new_components.md)

- [Testing in an application](./docs/contributing.md#testing-in-an-application)

- [Releasing](./docs/releasing.md)

## License

[Copyright 2021, TrussWorks, Inc.](./LICENSE)

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    

      
_{Suzanne Rozier}
💻 📖

      
_haworku
💻 📖

      
_{Andrew Hobson}
💻

      
_{John Gedeon}
💻 🚧

      
_{Emily Mahanna}
💻

      
_{Brandon Lenz}
💻 📖 🚧 🐛

      
_{Jeri Sommers}
💻

    

    

      
_{Erin Stanfill}
💻

      
_{Barry Morrison}
💻

      
_Duncan
💻

      
_{Arianna Kellogg}
💻

      
_{Christopher Hui}
💻

      
_{Jim Benton}
💻

      
_{Jen Duong}
💻

    

    

      
_{Kim Allen}
💻 ️️️️♿️

      
_{Kyle Hill}
💻

      
_{Mazdak Atighi}
💻

      
_{Isaac Garfinkle}
💻

      
_{Roger Steve Ruiz}
💻 📖

      
_{Leo Singer}
🐛 💻

      
_{Shauna Keating}
️️️️♿️ 💻

    

    

      
_{Jacob Capps}
💻

      
_pearl-truss
💻

      
_{Andrew Nelson}
💻 📖 🚧 🐛 ️️️️♿️

      
_{Sawyer Hollenshead}
💻 🐛

      
_{Ryan Delaney}
🚧 🚇

      
_{Anna Gingle}
🎨 💻

      
_{Abdullah Umer}
💻

    

    

      
_{Muhammad Adeel}
🐛 💻

      
_{Vinod Krishna Vellampalli}
💻

      
_{Joe Kleinschmidt}
💻

      
_{James Hancock}
🐛 💻

      
_{Joseph Andersen}
💻 🚧 🚇

      
_{Courtney Eimerman-Wallace}
🚧

      
_{Owen Coutts}
🐛 💻

    

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!