@zaide6137/m3-components-web 0.1.7 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Material 3 Components - Web
|
|
2
|
+
|
|
3
|
+
A modern React component library based on the **Material 3 (M3) Design System**. This library provides a powerful, dynamic theming engine that generates full color palettes from a single seed color and supports seamless light, dark, and auto mode switching.
|
|
4
|
+
|
|
5
|
+
<br>
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @zaide6137/m3-components-web
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
<br>
|
|
14
|
+
|
|
15
|
+
## Get Started
|
|
16
|
+
|
|
17
|
+
This Library is designed to be easy to use. The setup involves only 1 step to make everything work.
|
|
18
|
+
|
|
19
|
+
The first and only step required to setup the library is to wrap your root component with the `ThemeProvider` component.
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import { ThemeProvider } from '@zaide6137/m3-components-web';
|
|
23
|
+
|
|
24
|
+
export default function RootLayout({ children }) {
|
|
25
|
+
return (
|
|
26
|
+
<html>
|
|
27
|
+
<body>
|
|
28
|
+
<ThemeProvider
|
|
29
|
+
seedColor="#6750A4"
|
|
30
|
+
defaultColorScheme="auto"
|
|
31
|
+
>
|
|
32
|
+
{children}
|
|
33
|
+
</ThemeProvider>
|
|
34
|
+
</body>
|
|
35
|
+
</html>
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
For NextJS Users, wrap your `layout.tsx` with the `ThemeProvider`.
|
|
40
|
+
|
|
41
|
+
To customize the initial color of the entire components, modify the `seedColor` props of the `ThemeProvider` with the HEX Color Code you want. The seed color will be the basis of all the color pallete ThemeProvider will generate. It will automatically generate the appropriate Color Pallete based on the Material 3 Tokens. Check [this](https://m3.material.io/styles/color/roles) out to learn more about how Material 3 Color Roles & Tokens work.
|
|
42
|
+
|
|
43
|
+
To set the initial color scheme of the entire components, modify the `defaultColorScheme` prop of `ThemeProvider`. You can set it to Light, Dark and Automatic
|
|
44
|
+
|
|
45
|
+
<br>
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
## How It Works
|
|
49
|
+
The library works by auto generating the Material 3 Color Tokens based on the provided seed color. Then your app will utilize the `themeColors` object from the `useGlobalTheme()` hook to style your UI based on the Material 3 Design.
|
|
50
|
+
|
|
51
|
+
Built in components like `Button`, `Calendar`, `BigCalendar`, `EditText` from this library is already using the styles of `themeColors` automatically.
|
|
52
|
+
|
|
53
|
+
## Usage
|
|
54
|
+
|
|
55
|
+
<br>
|
|
56
|
+
|
|
57
|
+
### Accessing Theme Colors
|
|
58
|
+
Use the `useGlobalTheme` hook to access generated tokens. These colors reactively update when the theme or mode changes.
|
|
59
|
+
|
|
60
|
+
To style your custom UI like the background for your page, you can use the inline style method on the root div to set the background color of your page.
|
|
61
|
+
|
|
62
|
+
Example:
|
|
63
|
+
```tsx
|
|
64
|
+
"use client"
|
|
65
|
+
import { useGlobalTheme } from '@zaide6137/m3-components-web';
|
|
66
|
+
|
|
67
|
+
export default function MyHomePage(){
|
|
68
|
+
const { themeColors } = useGlobalTheme();
|
|
69
|
+
return (
|
|
70
|
+
<div
|
|
71
|
+
style={{
|
|
72
|
+
backgroundColor: themeColors.background
|
|
73
|
+
}}
|
|
74
|
+
>
|
|
75
|
+
<h1 style={{
|
|
76
|
+
color: themeColors.onSurface
|
|
77
|
+
}}
|
|
78
|
+
>
|
|
79
|
+
Hello World!
|
|
80
|
+
</h1>
|
|
81
|
+
</div>
|
|
82
|
+
)
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
<br>
|
|
86
|
+
|
|
87
|
+
### Change the Theme Colors
|
|
88
|
+
To change the entire brand color of your application, use the `setThemeColors` function. This takes a single hex color (the "seed") and automatically regenerates all Material 3 color tokens for your app instantly.
|
|
89
|
+
|
|
90
|
+
```tsx
|
|
91
|
+
"use client"
|
|
92
|
+
import { useGlobalTheme } from '@zaide6137/m3-components-web';
|
|
93
|
+
|
|
94
|
+
export default function BrandSwitcher() {
|
|
95
|
+
const { setThemeColors } = useGlobalTheme();
|
|
96
|
+
|
|
97
|
+
return (
|
|
98
|
+
<div>
|
|
99
|
+
{/* Updates the entire app palette to Teal tones */}
|
|
100
|
+
<button onClick={() => setThemeColors("#006A6A")}>
|
|
101
|
+
Set Brand to Teal
|
|
102
|
+
</button>
|
|
103
|
+
|
|
104
|
+
{/* Updates the entire app palette to Purple tones */}
|
|
105
|
+
<button onClick={() => setThemeColors("#6750A4")}>
|
|
106
|
+
Set Brand to Purple
|
|
107
|
+
</button>
|
|
108
|
+
</div>
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
<br>
|
|
113
|
+
|
|
114
|
+
### Theme Mode Switching
|
|
115
|
+
To switch between visual modes (Light, Dark, or System), use the `setColorScheme` function. This maintains your current brand color while shifting the background and surface tones to match the selected mode.
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
"use client"
|
|
119
|
+
import { useGlobalTheme } from '@zaide6137/m3-components-web';
|
|
120
|
+
|
|
121
|
+
export default function AppearanceSwitcher() {
|
|
122
|
+
const { setColorScheme } = useGlobalTheme();
|
|
123
|
+
|
|
124
|
+
return (
|
|
125
|
+
<div>
|
|
126
|
+
{/* Forces Light Mode */}
|
|
127
|
+
<button onClick={() => setColorScheme("light")}>
|
|
128
|
+
Light Mode
|
|
129
|
+
</button>
|
|
130
|
+
|
|
131
|
+
{/* Forces Dark Mode */}
|
|
132
|
+
<button onClick={() => setColorScheme("dark")}>
|
|
133
|
+
Dark Mode
|
|
134
|
+
</button>
|
|
135
|
+
|
|
136
|
+
{/* Automatically syncs with the user's OS settings */}
|
|
137
|
+
<button onClick={() => setColorScheme("auto")}>
|
|
138
|
+
System Preference
|
|
139
|
+
</button>
|
|
140
|
+
</div>
|
|
141
|
+
);
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
<br>
|
|
146
|
+
|
|
147
|
+
## License
|
|
148
|
+
MIT © Zaide LLC 2026
|