@whydrf/nava-icon-react 0.1.0 → 1.0.0
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/LICENSE +1 -1
- package/README.md +265 -0
- package/package.json +1 -1
package/LICENSE
CHANGED
package/README.md
ADDED
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/whydrf/nava-icon/main/docs/public/favicon.svg" width="60" alt="Nava Icons">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">@whydrf/nava-icon-react</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
950+ beautiful, tree-shakeable SVG icons for React applications.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://www.npmjs.com/package/@whydrf/nava-icon-react"><img src="https://img.shields.io/npm/v/@whydrf/nava-icon-react?style=flat-square&color=blue" alt="npm version"></a>
|
|
13
|
+
<a href="https://github.com/whydrf/nava-icon/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@whydrf/nava-icon-react?style=flat-square" alt="license"></a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/@whydrf/nava-icon-react"><img src="https://img.shields.io/npm/dm/@whydrf/nava-icon-react?style=flat-square&color=blue" alt="npm downloads"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## What is this?
|
|
20
|
+
|
|
21
|
+
`@whydrf/nava-icon-react` is the React binding for [Nava Icons](https://github.com/whydrf/nava-icon) — a collection of 950+ handcrafted SVG icons. Each icon is a native React component with full TypeScript support, tree shaking, and two visual variants (regular outlines and filled shapes).
|
|
22
|
+
|
|
23
|
+
Unlike icon fonts or SVG sprites, every icon here is a proper React component. You import it, use it with JSX props, and your bundler eliminates anything you didn't import.
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @whydrf/nava-icon-react
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Requirements:** React 18 or later. Works with both the App Router and Pages Router in Next.js.
|
|
32
|
+
|
|
33
|
+
## Getting Started
|
|
34
|
+
|
|
35
|
+
After installation, import the icons you need by name. Every icon follows the pattern `{IconName}Icon` in PascalCase:
|
|
36
|
+
|
|
37
|
+
```tsx
|
|
38
|
+
import { HomeIcon, SearchIcon, SettingsIcon } from '@whydrf/nava-icon-react'
|
|
39
|
+
|
|
40
|
+
export function Navigation() {
|
|
41
|
+
return (
|
|
42
|
+
<nav>
|
|
43
|
+
<HomeIcon size={24} />
|
|
44
|
+
<SearchIcon size={24} color="gray" />
|
|
45
|
+
<SettingsIcon size={24} />
|
|
46
|
+
</nav>
|
|
47
|
+
)
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
That's it — no provider, no context, no configuration. Just import and use.
|
|
52
|
+
|
|
53
|
+
## How Tree Shaking Works
|
|
54
|
+
|
|
55
|
+
This is the most important concept to understand. When you write:
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
import { HomeIcon } from '@whydrf/nava-icon-react'
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Your bundler (webpack, Vite, Rollup, esbuild) traces this import and includes **only** the `HomeIcon` component in your production bundle. The other 949 icons are completely eliminated. This is why static imports are strongly recommended.
|
|
62
|
+
|
|
63
|
+
In contrast, this pattern imports everything:
|
|
64
|
+
|
|
65
|
+
```tsx
|
|
66
|
+
// ❌ Don't do this in production — bundles all 950+ icons
|
|
67
|
+
import * as Icons from '@whydrf/nava-icon-react'
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
If you need to render icons dynamically (e.g., the icon name comes from a database or user input), use the `Icon` component instead. It's designed for that specific use case and clearly documents the bundle size trade-off.
|
|
71
|
+
|
|
72
|
+
## Two Variants: Regular and Filled
|
|
73
|
+
|
|
74
|
+
Every icon in the library ships in two visual styles:
|
|
75
|
+
|
|
76
|
+
- **Regular** — Stroke-based outlines. Clean, minimal, and ideal for most UI contexts like navigation, toolbars, and forms.
|
|
77
|
+
- **Filled** — Solid shapes with filled regions. Great for emphasis, active states, or when you want an icon to stand out.
|
|
78
|
+
|
|
79
|
+
You control which variant to show with the `mode` prop:
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import { CheckCircleIcon, HeartIcon } from '@whydrf/nava-icon-react'
|
|
83
|
+
|
|
84
|
+
function StatusIndicator({ isComplete }: { isComplete: boolean }) {
|
|
85
|
+
return (
|
|
86
|
+
<div>
|
|
87
|
+
{/* Show a filled heart when liked, outline when not */}
|
|
88
|
+
<HeartIcon
|
|
89
|
+
size={24}
|
|
90
|
+
mode={isComplete ? 'filled' : 'regular'}
|
|
91
|
+
color={isComplete ? 'red' : 'gray'}
|
|
92
|
+
/>
|
|
93
|
+
|
|
94
|
+
{/* Always show filled for completed tasks */}
|
|
95
|
+
<CheckCircleIcon size={24} mode="filled" color="green" />
|
|
96
|
+
</div>
|
|
97
|
+
)
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The mode switching is instant — no re-fetching, no lazy loading. Both variants are bundled together.
|
|
102
|
+
|
|
103
|
+
## The Dynamic `Icon` Component
|
|
104
|
+
|
|
105
|
+
Sometimes you can't use static imports. Maybe the icon name comes from an API, a database, or user configuration. For these cases, the package exports a dynamic `Icon` component:
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import { Icon } from '@whydrf/nava-icon-react'
|
|
109
|
+
|
|
110
|
+
// The name prop accepts kebab-case strings
|
|
111
|
+
<Icon name="home" size={24} />
|
|
112
|
+
<Icon name="check-circle" mode="filled" color="green" />
|
|
113
|
+
<Icon name="arrow-right" size={16} />
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Important:** The `Icon` component imports all icons internally, so it cannot be tree-shaken. Your bundle will include all 950+ icons. Use it only when static imports aren't feasible.
|
|
117
|
+
|
|
118
|
+
## Customizing Appearance
|
|
119
|
+
|
|
120
|
+
Since icons are standard SVG elements, you can customize them with CSS and standard React props:
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
<HomeIcon
|
|
124
|
+
size={32}
|
|
125
|
+
color="#6366f1"
|
|
126
|
+
strokeWidth={1}
|
|
127
|
+
className="icon-hover"
|
|
128
|
+
style={{ transition: 'transform 0.2s', cursor: 'pointer' }}
|
|
129
|
+
onClick={() => navigate('/')}
|
|
130
|
+
aria-label="Go to homepage"
|
|
131
|
+
/>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The `className` and `style` props work exactly like any HTML element. You can target icons with CSS selectors, add transitions, animations, or theme them with CSS variables.
|
|
135
|
+
|
|
136
|
+
### Colors
|
|
137
|
+
|
|
138
|
+
You can pass colors in any format the browser understands — hex codes, RGB, HSL, named colors, or CSS variables:
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
<HomeIcon color="#1a1a2e" /> {/* Hex */}
|
|
142
|
+
<HomeIcon color="rgb(99, 102, 241)" /> {/* RGB */}
|
|
143
|
+
<HomeIcon color="oklch(65% 0.27 264)" /> {/* OKLCH */}
|
|
144
|
+
<HomeIcon color="var(--primary)" /> {/* CSS variable */}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
With **Tailwind CSS**, wrap the icon in a utility class and use `currentColor`:
|
|
148
|
+
|
|
149
|
+
```tsx
|
|
150
|
+
// The color prop defaults to currentColor, so Tailwind's text-* utilities work directly
|
|
151
|
+
<HomeIcon className="text-blue-500" />
|
|
152
|
+
|
|
153
|
+
// Combine color, size, and hover effects
|
|
154
|
+
<HomeIcon className="text-emerald-400 w-8 h-8 hover:text-emerald-300 transition-colors" />
|
|
155
|
+
|
|
156
|
+
// Dark mode support
|
|
157
|
+
<HomeIcon className="text-gray-900 dark:text-white" />
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Accessibility
|
|
161
|
+
|
|
162
|
+
Icons include built-in accessibility features:
|
|
163
|
+
|
|
164
|
+
- When you provide a `title` prop, an invisible `<title>` element is added inside the SVG, which screen readers announce.
|
|
165
|
+
- Decorative icons (no `title`) are implicitly `aria-hidden` since SVGs without titles are ignored by assistive technology.
|
|
166
|
+
|
|
167
|
+
```tsx
|
|
168
|
+
// Meaningful icon — screen reader announces "Go to homepage"
|
|
169
|
+
<HomeIcon title="Go to homepage" />
|
|
170
|
+
|
|
171
|
+
// Decorative icon — screen reader ignores it
|
|
172
|
+
<HomeIcon />
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Server-Side Rendering
|
|
176
|
+
|
|
177
|
+
Nava Icons works with SSR out of the box. Icons are rendered as regular HTML/SVG elements — there's no client-side JavaScript required to display them.
|
|
178
|
+
|
|
179
|
+
### Next.js App Router (Server Components)
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
// This works in a Server Component — no 'use client' needed
|
|
183
|
+
import { HomeIcon } from '@whydrf/nava-icon-react'
|
|
184
|
+
|
|
185
|
+
export default function Page() {
|
|
186
|
+
return <HomeIcon size={24} />
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Next.js Pages Router
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
// Works in both getServerSideProps and regular components
|
|
194
|
+
import { HomeIcon } from '@whydrf/nava-icon-react'
|
|
195
|
+
|
|
196
|
+
export default function Page() {
|
|
197
|
+
return <HomeIcon size={24} />
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## TypeScript
|
|
202
|
+
|
|
203
|
+
The package includes full TypeScript definitions. You get autocompletion for icon names and type checking for all props:
|
|
204
|
+
|
|
205
|
+
```tsx
|
|
206
|
+
import type { IconName, IconMode, IconProps } from '@whydrf/nava-icon-react'
|
|
207
|
+
|
|
208
|
+
// IconName gives you autocompletion for all 950+ icon names
|
|
209
|
+
const icon: IconName = 'home' // ✅ valid
|
|
210
|
+
const bad: IconName = 'invalid' // ❌ compile error
|
|
211
|
+
|
|
212
|
+
// IconMode constrains to 'regular' | 'filled'
|
|
213
|
+
const mode: IconMode = 'filled' // ✅
|
|
214
|
+
|
|
215
|
+
// IconProps for extending the component
|
|
216
|
+
function CustomIcon(props: IconProps) {
|
|
217
|
+
return <HomeIcon {...props} />
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Props Reference
|
|
222
|
+
|
|
223
|
+
| Prop | Type | Default | Description |
|
|
224
|
+
|------|------|---------|-------------|
|
|
225
|
+
| `size` | `number \| string` | `24` | Width and height in pixels |
|
|
226
|
+
| `color` | `string` | `currentColor` | SVG stroke/fill color. `currentColor` inherits from parent CSS |
|
|
227
|
+
| `strokeWidth` | `number \| string` | `0.5` | Controls line thickness for stroke-based icons |
|
|
228
|
+
| `mode` | `"regular" \| "filled"` | `"regular"` | Toggles between outline and solid variants |
|
|
229
|
+
| `title` | `string` | — | Accessible title for screen readers |
|
|
230
|
+
| `className` | `string` | — | CSS class name |
|
|
231
|
+
| `style` | `CSSProperties` | — | Inline styles |
|
|
232
|
+
|
|
233
|
+
All standard SVG attributes (`onClick`, `onMouseEnter`, `data-*`, `aria-*`, etc.) are also supported.
|
|
234
|
+
|
|
235
|
+
## Popular Icons
|
|
236
|
+
|
|
237
|
+
| Category | Icons |
|
|
238
|
+
|----------|-------|
|
|
239
|
+
| **Arrows** | `arrow-back`, `arrow-right`, `arrow-from-left`, `arrow-to-top`, `refresh`, `redo`, `undo` |
|
|
240
|
+
| **Interface** | `home`, `search`, `settings`, `menu`, `check-circle`, `x-circle`, `copy`, `trash` |
|
|
241
|
+
| **Communication** | `bell`, `mail`, `phone`, `message-square`, `send`, `at` |
|
|
242
|
+
| **Files** | `file`, `folder`, `download`, `upload`, `archive`, `clipboard` |
|
|
243
|
+
| **Media** | `camera`, `image`, `music`, `video`, `play`, `pause` |
|
|
244
|
+
| **Objects** | `star`, `bookmark`, `lock`, `key`, `award`, `gift` |
|
|
245
|
+
| **Weather** | `sun`, `moon`, `cloud`, `droplet`, `wind`, `umbrella` |
|
|
246
|
+
| **Shopping** | `cart`, `credit-card`, `bag`, `tag`, `badge`, `diamond` |
|
|
247
|
+
|
|
248
|
+
Browse all 950+ icons with live preview at [**nava-icons.dev**](https://nava-icons.dev).
|
|
249
|
+
|
|
250
|
+
## Comparing with Alternatives
|
|
251
|
+
|
|
252
|
+
| | Nava Icons | react-icons | Heroicons | Lucide |
|
|
253
|
+
|---|---|---|---|---|
|
|
254
|
+
| Icons | 950+ | 5000+ | 300+ | 1500+ |
|
|
255
|
+
| Variants | Regular + Filled | Varies by set | Outline + Solid | Stroke only |
|
|
256
|
+
| Tree shaking | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
|
|
257
|
+
| TypeScript | ✅ | Partial | ✅ | ✅ |
|
|
258
|
+
| Dynamic API | ✅ | ✅ | ❌ | ❌ |
|
|
259
|
+
| SSR | ✅ | ✅ | ✅ | ✅ |
|
|
260
|
+
|
|
261
|
+
Nava Icons strikes a balance between quantity and quality — every icon is designed with the same visual language, so your UI stays consistent.
|
|
262
|
+
|
|
263
|
+
## License
|
|
264
|
+
|
|
265
|
+
[MIT](https://github.com/whydrf/nava-icon/blob/main/LICENSE) © [whydrf](https://github.com/whydrf)
|