@usenavii/react 0.1.0 → 0.2.1
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 +119 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# @usenavii/react
|
|
2
|
+
|
|
3
|
+
**React binding for [Navii](https://navii.uxderrick.com) — deterministic mascot avatars.**
|
|
4
|
+
Drop a `<Navii seed={user.id} />` and every user has a face, no uploads.
|
|
5
|
+
|
|
6
|
+
<p align="center">
|
|
7
|
+
<img src="https://navii-api.uxderrick.com/group?seeds=aria,milo,nova,kai,sage,eden,luna,rio,pip,wren,zane,iris&size=72&overlap=0.32&ring=%230a0a0b&tileBg=%23ffffff" alt="Navii cast" />
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
- [Live demo](https://navii.uxderrick.com)
|
|
11
|
+
- [Docs](https://navii.uxderrick.com/docs)
|
|
12
|
+
- [GitHub](https://github.com/uxderrick/navii)
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm add @usenavii/react
|
|
18
|
+
pnpm add @usenavii/react
|
|
19
|
+
yarn add @usenavii/react
|
|
20
|
+
bun add @usenavii/react
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
React `>=17` is a peer dep. `@usenavii/core` is auto-installed.
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { Navii } from '@usenavii/react';
|
|
29
|
+
|
|
30
|
+
<Navii
|
|
31
|
+
seed={user.id}
|
|
32
|
+
size={64}
|
|
33
|
+
title={user.name}
|
|
34
|
+
animated
|
|
35
|
+
/>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Renders as a memoized `<img src="data:image/svg+xml;...">` so the SVG is treated as opaque by the browser — no inline scripting surface.
|
|
39
|
+
|
|
40
|
+
## Props
|
|
41
|
+
|
|
42
|
+
| Prop | Type | Default |
|
|
43
|
+
| ------------ | ----------------------------------------------------- | ------------ |
|
|
44
|
+
| `seed` | `string` — **required** | — |
|
|
45
|
+
| `size` | `number` (px) | `96` |
|
|
46
|
+
| `paletteId` | known palette id (e.g. `'mint'`) | seed-derived |
|
|
47
|
+
| `background` | `'none' \| 'solid' \| 'ring'` or `{ color }` | seed-derived |
|
|
48
|
+
| `tileBg` | CSS color or `'auto'` (palette accent) | none |
|
|
49
|
+
| `title` | accessible label | none |
|
|
50
|
+
| `animated` | `boolean` — idle float / blink / sway / twinkle | `false` |
|
|
51
|
+
| `alt` | image alt text (falls back to `title`) | `''` |
|
|
52
|
+
| `className` | passed through to `<img>` | — |
|
|
53
|
+
| `style` | passed through to `<img>` | — |
|
|
54
|
+
|
|
55
|
+
## The seed: read this once
|
|
56
|
+
|
|
57
|
+
Same seed always produces the same avatar — that's the contract.
|
|
58
|
+
|
|
59
|
+
| Pass | Result |
|
|
60
|
+
| -------------------------- | ------------------------------------------------------- |
|
|
61
|
+
| `user.id` / UUID | ✅ Best. Stable and globally unique. |
|
|
62
|
+
| `user.email` | ✅ Good. Stable, unique per user. |
|
|
63
|
+
| `user.name` alone | ⚠️ Names collide. Two "Alice"s get the same avatar. |
|
|
64
|
+
| `${name}-${createdAt}` | ✅ Fine fallback if no ID exists. Bake at signup. |
|
|
65
|
+
| `Date.now()` at render | ❌ **Don't.** Breaks determinism — changes on reload. |
|
|
66
|
+
|
|
67
|
+
Need a helper that picks the right field automatically?
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { seed } from '@usenavii/core';
|
|
71
|
+
|
|
72
|
+
const s = seed({ id: user.id, email: user.email, name: user.name });
|
|
73
|
+
<Navii seed={s} />
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Example use cases
|
|
77
|
+
|
|
78
|
+
### Profile card
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
function UserCard({ user }) {
|
|
82
|
+
return (
|
|
83
|
+
<div className="user-card">
|
|
84
|
+
<Navii seed={user.id} size={64} title={user.name} />
|
|
85
|
+
<div>
|
|
86
|
+
<strong>{user.name}</strong>
|
|
87
|
+
<span>{user.email}</span>
|
|
88
|
+
</div>
|
|
89
|
+
</div>
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Team list
|
|
95
|
+
|
|
96
|
+
```tsx
|
|
97
|
+
{team.map(u => (
|
|
98
|
+
<Navii key={u.id} seed={u.id} size={48} title={u.name} />
|
|
99
|
+
))}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Photo fallback
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
<img
|
|
106
|
+
src={user.photoUrl}
|
|
107
|
+
onError={(e) => { e.currentTarget.src = `https://navii-api.uxderrick.com/avatar/${encodeURIComponent(user.id)}`; }}
|
|
108
|
+
/>
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Or render `<Navii>` directly when `photoUrl` is null — no fetch needed, deterministic.
|
|
112
|
+
|
|
113
|
+
## Determinism guarantee
|
|
114
|
+
|
|
115
|
+
Same seed + same options → byte-identical SVG. Memoized on `seed + size + paletteId + background + tileBg + title + animated`. Re-renders with same props don't re-run the engine.
|
|
116
|
+
|
|
117
|
+
## License
|
|
118
|
+
|
|
119
|
+
MIT. See [LICENSE](https://github.com/uxderrick/navii/blob/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@usenavii/react",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "React binding for Navii deterministic avatars — <Navii seed=\"...\" />.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.cjs",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"access": "public"
|
|
42
42
|
},
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"@usenavii/core": "^0.1
|
|
44
|
+
"@usenavii/core": "^0.2.1"
|
|
45
45
|
},
|
|
46
46
|
"peerDependencies": {
|
|
47
47
|
"react": ">=17"
|