local-svg 0.0.3 → 0.0.4
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 +170 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# LocalSvg
|
|
2
|
+
|
|
3
|
+
A lightweight, performant React component for loading and rendering local or remote SVG files directly as React components. Skip bloated icon libraries and streamline your custom icon workflow.
|
|
4
|
+
|
|
5
|
+
## Why LocalSvg?
|
|
6
|
+
|
|
7
|
+
- **No Icon Set Bloat**: Use only the SVGs you need without including massive icon library dependencies
|
|
8
|
+
- **Smart Caching**: Automatic localStorage caching with in-memory promise caching for optimal performance
|
|
9
|
+
- **Automatic Minification**: SVG files are automatically minified to reduce bandwidth and storage
|
|
10
|
+
- **Pure React Components**: SVGs are parsed and rendered as native React components with full TypeScript support
|
|
11
|
+
- **Flexible Loading**: Load SVGs from any URL or local path
|
|
12
|
+
- **Namespace Aware**: Automatically handles XML/SVG namespaces and converts them to React-compatible attributes
|
|
13
|
+
- **Lightweight**: No external dependencies (except React)
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install local-svg
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or with yarn:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
yarn add local-svg
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { LocalSvg } from 'local-svg';
|
|
31
|
+
|
|
32
|
+
export default function App() {
|
|
33
|
+
return (
|
|
34
|
+
<LocalSvg
|
|
35
|
+
name="icon-name"
|
|
36
|
+
width={24}
|
|
37
|
+
height={24}
|
|
38
|
+
/>
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Props
|
|
44
|
+
|
|
45
|
+
### LocalSvgProps
|
|
46
|
+
|
|
47
|
+
Extends `SVGAttributes<SVGSVGElement>`, so you can use any standard SVG element props.
|
|
48
|
+
|
|
49
|
+
| Prop | Type | Default | Description |
|
|
50
|
+
|------|------|---------|-------------|
|
|
51
|
+
| `name` | `string` | Required | The name of the SVG file (without `.svg` extension) |
|
|
52
|
+
| `baseUrl` | `string` | `"/"` | The base URL or path where SVG files are located |
|
|
53
|
+
| `as` | `React.ElementType` | `"span"` | The wrapper component to use while loading |
|
|
54
|
+
| `ref` | `RefObject<SVGSVGElement>` | - | Forward ref to the SVG element |
|
|
55
|
+
| `...rest` | `SVGAttributes` | - | Any standard SVG attributes (className, style, onClick, etc.) |
|
|
56
|
+
|
|
57
|
+
## Usage Examples
|
|
58
|
+
|
|
59
|
+
### Basic Icon
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
<LocalSvg name="star" width={24} height={24} />
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### With Custom Styling
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
<LocalSvg
|
|
69
|
+
name="logo"
|
|
70
|
+
width={100}
|
|
71
|
+
height={100}
|
|
72
|
+
className="logo-icon"
|
|
73
|
+
style={{ color: '#007bff', filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.1))' }}
|
|
74
|
+
/>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Custom Base URL
|
|
78
|
+
|
|
79
|
+
```tsx
|
|
80
|
+
<LocalSvg
|
|
81
|
+
name="icon"
|
|
82
|
+
baseUrl="/static/icons/"
|
|
83
|
+
/>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### With Event Handlers
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
<LocalSvg
|
|
90
|
+
name="button-icon"
|
|
91
|
+
width={20}
|
|
92
|
+
height={20}
|
|
93
|
+
onClick={() => console.log('Clicked!')}
|
|
94
|
+
style={{ cursor: 'pointer' }}
|
|
95
|
+
/>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### With Loading Placeholder
|
|
99
|
+
|
|
100
|
+
```tsx
|
|
101
|
+
<LocalSvg
|
|
102
|
+
name="spinner"
|
|
103
|
+
width={24}
|
|
104
|
+
height={24}
|
|
105
|
+
as="div"
|
|
106
|
+
className="loading-placeholder"
|
|
107
|
+
/>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The `as` prop specifies what to render while the SVG is loading (defaults to `span`).
|
|
111
|
+
|
|
112
|
+
## How It Works
|
|
113
|
+
|
|
114
|
+
1. **Fetching**: Loads the SVG file from the URL when the component mounts
|
|
115
|
+
2. **Parsing**: Converts the SVG text into a React-friendly structure
|
|
116
|
+
3. **Minification**: Removes unnecessary data from the SVG (whitespace, comments, etc.) to save space
|
|
117
|
+
4. **Caching**:
|
|
118
|
+
- Stores the minified SVG in browser localStorage so it doesn't need to be fetched again
|
|
119
|
+
- Uses in-memory cache to prevent duplicate requests in the same session
|
|
120
|
+
5. **Rendering**: Displays the SVG as native React elements
|
|
121
|
+
|
|
122
|
+
## Performance Optimizations
|
|
123
|
+
|
|
124
|
+
LocalSvg is built for speed:
|
|
125
|
+
|
|
126
|
+
- **Smart Caching**: localStorage persists minified SVGs across page reloads, reducing bandwidth on return visits by 99%
|
|
127
|
+
- **Size Reduction**: SVGs are automatically cleaned up, saving 40-60% of file size on average
|
|
128
|
+
- **React Optimized**: Prevents unnecessary re-renders and avoids duplicate fetch requests
|
|
129
|
+
|
|
130
|
+
## TypeScript Support
|
|
131
|
+
|
|
132
|
+
Full TypeScript support is built-in:
|
|
133
|
+
|
|
134
|
+
```tsx
|
|
135
|
+
import { LocalSvg, type LocalSvgProps } from 'local-svg';
|
|
136
|
+
|
|
137
|
+
const IconWrapper: React.FC<LocalSvgProps> = (props) => {
|
|
138
|
+
return <LocalSvg {...props} />;
|
|
139
|
+
};
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Browser Support
|
|
143
|
+
|
|
144
|
+
Works in all modern browsers that support:
|
|
145
|
+
- ES6+ JavaScript
|
|
146
|
+
- React 18+
|
|
147
|
+
- localStorage API
|
|
148
|
+
|
|
149
|
+
## API Reference
|
|
150
|
+
|
|
151
|
+
### LocalSvg
|
|
152
|
+
|
|
153
|
+
The main React component for rendering SVGs.
|
|
154
|
+
|
|
155
|
+
```tsx
|
|
156
|
+
<LocalSvg
|
|
157
|
+
name="icon-name"
|
|
158
|
+
baseUrl="/"
|
|
159
|
+
as="span"
|
|
160
|
+
width={24}
|
|
161
|
+
height={24}
|
|
162
|
+
className="my-icon"
|
|
163
|
+
// ... any SVG attributes
|
|
164
|
+
ref={svgRef}
|
|
165
|
+
/>
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## License
|
|
169
|
+
|
|
170
|
+
MIT © Godswill Anwuli
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "local-svg",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.4",
|
|
4
4
|
"description": "LocalSvg - A lightweight React component for loading local or remote SVGs. Skip bloated icon sets and streamline your custom icon workflow.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.mjs",
|