react-md
react-md

This project's goal is to create fully accessible React components following the accessibility guidelines from www.w3.org that will also be easily customizable with sensible defaults following the Material Design principals. The components are created to feel like "extension of the DOM and native HTML Elements" meaning using a <Button> component from react-md should behave the same as using a <button> element.

The styles can be configured both compile-time and run-time by the configurable SCSS variables and the usage of CSS Variables as well as ensuring that the last defined styles take precedence. In addition, since accessibility is a focus for this library, the theming will automatically attempt to fix color contrast ratios for you to meet at least the AA requirements along with right to left language support.

Getting Started

To get started, you must first install react-md. Next, you should include the Roboto font and optionally material-icons if using font icons. Check out the full installation page for more info about updating existing applications, create-react-app, or next.js

Get started!
Components and Styles

Once you've installed react-md, it's time to check out all the components that are available and how to use them.

<Button id="example-button" onClick={() => console.log("I was clicked!")}>
  Example Button
</Button>
See Examples!
Customization and Themes

Now that you've gotten the hang of using components from react-md, it's time to make your app feel unique! There's no point in having every app look exactly the same especially when you need to add your company's branding.

Customize!

Before you choosing this library, it is highly recommended to check out the pros and cons list below.

ProsCons
Styling
  • Styles provided by SCSS.
  • Styles are designed so that the last defined and/or included styles take precedence. Ensures that adding a custom classNameto a component should always override the defaultreact-md styles.
  • Configurable theming and for dark mode support.
  • Built-in support for RTL languages.
  • Sensible defaults that can be overridden and opted-out to minify bundle size.
  • Multiple mixins and functions to dynamically update your theme with built-in validation and warning messages when used incorrectly.
  • 2300+ pre-built themes available through the unpkg CDN.
  • Works with CSS Modules.
  • Should work with any CSS-in-JS solution.
  • Styles provided by SCSS (Only a con if you are unfamiliar with SCSS).
  • Requires additional setup for including styles by either building the styles yourself or including one of the pre-built themes
  • Initial build time is fairly slow due to fixing color contrast ratios. Workaround possible by prebuilding the base styles.
  • Reusing styleable variables will be slighty more difficult in CSS-in-JS solutions. However, the default variable names and their values are available in each package in the dist/scssVariables.js export.
Components
  • More than 80 exported components.
  • Components are low-level which allows for a lot of customization.
  • Can be thought of as an extension of native HTML Elements. Every prop available on the native counterpart are available and refs are forwarded to the DOM node.
  • Strictly typed in Typescript and loosely typed with PropTypes.
  • Components are low-level which requires creating your own high-level components for repeated functionality or patterns.
  • Typescript types can be improved when generics are involved.
Accessibility
  • Attempts to fix color contrast ratios automatically.
  • Implements keyboard movement and searching for known accessible widgets.
  • Maintains tab focus even while navigating through nested menus or dialogs.
  • Adds warnings when different aria-* props are required but were omitted.
  • Unable to fix all color contrast ratio issues automatically.
  • Most components require a unique id prop for accessibility concerns.
  • Components might require a string version of the children to be keyboard searchable.
Documentation
  • All components, hooks, and utility functions are written and maintained in Typescript.
  • All types are exported at the package root for convenience and are documented with Typedoc.
  • Editor/IDE documentation integration if the "Go to Definition" functionality is supported.
  • All SCSS variables, functions, and mixins are documented with SassDoc.
  • Multiple demos, common patterns, and use cases provided for each package.
  • English is the only official documentation language at this time.
  • Some Typescript types could be improved
Other
  • A fairly small library size (gzipped):
    • Production UMD Bundle:
      92.51 kB
    • Default Production CSS Bundles:
      18.08 kB - 18.15 kB
  • Internet Explorer 11 is not fully supported.
  • Probably overkill for small projects.
  • This is a side project for the one active developer.
  • Does not have a fully active community.
  • Releases will be slow.