Skip to content

trussworks/react-uswds

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@trussworks/react-uswds

All Contributors

npm version uswds version

npm downloads

ReactUSWDS Component Library

This is a frontend component library, built in React with Typescript, based on design patterns defined by the United States Web Design System (USWDS) 3.0. 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/

Table of Contents

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

Having issues? See FAQs.

NodeJS

We develop on this library with the version of node defined in .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 exxpect to support, if you are using a pre-release or development version of node you may run into unexpected issues.

Having issues? See FAQs.

Pre-Release

See prelease.md

Implementation examples

We decided to focus on our storybook over hosting an example/boilerplate implementation, but you can find a few such things from our friends:

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

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

Active Maintainers

We are starting to rotate Trussel maintainer responsibilities. Check out the maintainers README.

Contributing

Interested in contributing? See our guidelines and dev setup here.

Are you a Trussel and new to this project? Check out our on & offboarding guide made just for you!

This repository is governed by the Contributor Covenant

Quick links:

License

Copyright 2021, TrussWorks, Inc.

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

Suzanne Rozier
Suzanne Rozier

πŸ’» πŸ“–
haworku
haworku

πŸ’» πŸ“–
Andrew Hobson
Andrew Hobson

πŸ’»
John Gedeon
John Gedeon

πŸ’» 🚧
Emily Mahanna
Emily Mahanna

πŸ’»
Brandon Lenz
Brandon Lenz

πŸ’» πŸ“– 🚧 πŸ›
Jeri Sommers
Jeri Sommers

πŸ’»
Erin Stanfill
Erin Stanfill

πŸ’»
Barry Morrison
Barry Morrison

πŸ’»
Duncan
Duncan

πŸ’»
Arianna Kellogg
Arianna Kellogg

πŸ’»
Christopher Hui
Christopher Hui

πŸ’»
Jim Benton
Jim Benton

πŸ’»
Jen Duong
Jen Duong

πŸ’»
Kim Allen
Kim Allen

πŸ’» ️️️️♿️
Kyle Hill
Kyle Hill

πŸ’»
Mazdak Atighi
Mazdak Atighi

πŸ’»
Isaac Garfinkle
Isaac Garfinkle

πŸ’»
Roger Steve Ruiz
Roger Steve Ruiz

πŸ’» πŸ“–
Leo Singer
Leo Singer

πŸ› πŸ’»
Shauna Keating
Shauna Keating

️️️️♿️ πŸ’»
Jacob Capps
Jacob Capps

πŸ’»
pearl-truss
pearl-truss

πŸ’»
Andrew Nelson
Andrew Nelson

πŸ’» πŸ“– 🚧 πŸ› ️️️️♿️
Sawyer Hollenshead
Sawyer Hollenshead

πŸ’» πŸ›
Ryan Delaney
Ryan Delaney

🚧 πŸš‡
Anna Gingle
Anna Gingle

🎨 πŸ’»
Abdullah Umer
Abdullah Umer

πŸ’»
Muhammad Adeel
Muhammad Adeel

πŸ› πŸ’»
Vinod Krishna Vellampalli
Vinod Krishna Vellampalli

πŸ’»
Joe Kleinschmidt
Joe Kleinschmidt

πŸ’»
James Hancock
James Hancock

πŸ› πŸ’»
Joseph Andersen
Joseph Andersen

πŸ’» 🚧 πŸš‡
Courtney Eimerman-Wallace
Courtney Eimerman-Wallace

🚧
Owen Coutts
Owen Coutts

πŸ› πŸ’»

This project follows the all-contributors specification. Contributions of any kind welcome!