README.md

Soda

     

A React (>=18) component library that follows Material Design 3 (a.k.a. Material You).

Features:

• Fewer dependencies (bundled in the npm package)
• Follows the Material You design
• Complete implementation of Material You components
• Keyboard accessibility
• Supports both controlled and uncontrolled components

Warning

Work in progress, API is unstable and can change at any time.
For production, you may want to use the official material web component library or the MDUI library.

This is an experimental project with the best browser support for:
Chrome >= 105, Safari >= 15.4, Firefox >= 121

The recommended browser is Chrome >= 119

Installation

npm install soda-material

import React from 'react'
import ReactDOM from 'react-dom/client'
import 'soda-material/dist/style.css' // Note that you MUST import the style
import { Button } from 'soda-material'

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <Button variant="outlined">Button</Button>
    </React.StrictMode>,
)

If bundle size is your concern, it's also possible to import only specific components.

import 'soda-material/dist/style.css' // You still need to import the style somewhere
import { Button } from 'soda-material/dist/components/button'
import { Select } from 'soda-material/dist/composition/Select'

export default function App() {
    return (
        <>
            <Button variant="text">Button</Button>
            <Select options={['one', 'two', 'three']}></Select>
        </>
    )
}

Next.js is also supported out of the box.

Tip

This library is designed to maintain a small footprint, making it easy to integrate with other libraries in the ecosystem. For instance, it pairs well with Tailwind CSS, though it does not depend on it.

Documentation

See: https://soda.js.org

Important

Only components defined in the Material Design Docs will be included in the src/components directory. These components do NOT include heavy logic.
Other necessary components or helpers can be found in the src/composition directory.

Note

Most components in src/components forward the ref attribute for library interactivity.
If present, it will be the root DOM node of the entire component.
If not, it will be documented and will be checked if you use TypeScript.

TODO

• More ARIA support

• More customizable CSS variables

Development

npm install
npm run storybook

Naming convention:

• A .tsx file with a capitalized beginning is a React component (exports the same name, no default export)
• A .scss file will use hyphen to separate component names in the file name
• In any CSS code, use underscore to separate component names, use hyphen to separate name segments.