callstackincubator/apex-software-factory / .agents/skills/swm-react-native-best-practices
swm-react-native-best-practices
VerifiedSoftware Mansion's best practices for React Native and Expo on the New Architecture: Reanimated 4 animations, Gesture Handler, react-native-svg, and react-native-worklets threading. Read the sub-skill in references/ that matches the topic.
references/svg/svg.md
View on GitHub# React Native SVG
For the full component and prop API, webfetch https://github.com/software-mansion/react-native-svg/blob/main/USAGE.md
---
## Setup
### Expo
```bash
npx expo install react-native-svg
```
### React Native CLI
```bash
yarn add react-native-svg
cd ios && pod install
```
---
## Loading SVGs
### Inline components
```tsx
import Svg, { Circle, Rect } from "react-native-svg";
export default function InlineSvg() {
return (
<Svg height="100" width="100" viewBox="0 0 100 100">
<Circle cx="50" cy="50" r="45" stroke="blue" strokeWidth="2.5" fill="green" />
<Rect x="15" y="15" width="70" height="70" stroke="red" strokeWidth="2" fill="yellow" />
</Svg>
);
}
```
### From a remote URI
```tsx
import { SvgUri } from "react-native-svg";
export default function RemoteSvg() {
return <SvgUri width="100%" height="100%" uri="https://example.com/image.svg" />;
}
```
If the remote SVG contains CSS in a `<style>` element, use `SvgCssUri` from `react-native-svg/css` instead.
`SvgUri` and `SvgCssUri` support `onError`, `onLoad`, and `fallback` props for error handling:
```tsx
<SvgUri
uri={uri}
width="100%"
height="100%"
onError={() => setUri(fallbackUri)}
fallback={<FallbackComponent />}
/>
```
### From an XML string
```tsx
import { SvgXml } from "react-native-svg";
const xml = `<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="40" fill="red" /></svg>`;
export default function XmlSvg() {
return <SvgXml xml={xml} width="100%" height="100%" />;
}
```
If the XML string contains CSS in a `<style>` element, use `SvgCss` from `react-native-svg/css` instead.
### Importing `.svg` files directly
Use [react-native-svg-transformer](https://github.com/kristerkari/react-native-svg-transformer) for compile-time conversion with caching.
`metro.config.js` (react-native >= 0.72):
```js
const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
const defaultConfig = getDefaultConfig(__dirname);
const { assetExts, sourceExts } = defaultConfig.resolver;
const config = {
transformer: {
babelTransformerPath: require.resolve("react-native-svg-transformer"),
},
resolver: {
assetExts: assetExts.filter((ext) => ext !== "svg"),
sourceExts: [...sourceExts, "svg"],
},
};
module.exports = mergeConfig(defaultConfig, config);
```
Then import and use SVG files as components:
```tsx
import Logo from "./logo.svg";
<Logo width={120} height={40} />;
```
---
## Touch Events
SVG elements support `onPress`, `onPressIn`, `onPressOut`, `onLongPress`, `delayPressIn`, `delayPressOut`, `delayLongPress`, and `disabled`:
```tsx
<Circle cx="50%" cy="50%" r="38%" fill="red" onPress={() => alert("Pressed circle")} />
```
---
## Filters
Filter support is partial on native. The following filters work on all platforms:
- `FeBlend`, `FeComposite`, `FeColorMatrix`, `FeDropShadow`, `FeFlood`, `FeGaussianBlur`, `FeMerge`, `FeOffset`
```tsx
import { FeColorMatrix, Filter, Rect, Svg } from "react-native-svg";
export default function FilteredRect() {
return (
<Svg height="300" width="300">
<Filter id="desaturate">
<FeColorMatrix type="saturate" values="0.2" />
</Filter>
<Rect x="0" y="0" width="300" height="300" fill="red" filter="url(#desaturate)" />
</Svg>
);
}
```
### FilterImage
`FilterImage` applies filters to raster images. Import from `react-native-svg/filter-image`. Filters can be applied via the `filters` prop (array) or via the CSS `filter` style property:
```tsx
import { FilterImage } from "react-native-svg/filter-image";
<FilterImage
style={{ width: 200, height: 200, filter: "saturate(3) grayscale(100%)" }}
source={require("./photo.jpg")}
/>;
```
---
## Performance
- **Every SVG element becomes a native view.** A complex SVG creates a full React component tree and a matching native view hierarchy. None are memoized by default, so every re-render reconciles the entire tree.
- **No drawing cache.** Each native drawing dispatch redraws everything from scratch.
- **`SvgXml` and `LocalSvg` have the same overhead.** They parse SVG content into the same React component tree under the hood. You lose direct control over individual elements without gaining any performance benefit.
- **Memory leaks on iOS.** Dependencies between element props can be deeply nested, and some platform primitives don't support automatic memory management, making leaks hard to track down.
- **For static SVG content, prefer `expo-image` or `react-native-vector-image`** over `react-native-svg`. See `when-to-use.md` for a full comparison.
---
## Known Issues
1. Unable to apply focus point of `RadialGradient` on Android.
2. Unable to animate SVG on Paper (Old Architecture).
3. Many SVG filters are web-only and will show a warning on native.
4. Memory leaks on iOS caused by deeply nested element prop dependencies and platform primitives without automatic memory management.
---
## Tips
- Find SVGs at the [Noun Project](https://thenounproject.com/).
- Create or edit SVGs with [Figma](https://www.figma.com/).
- Optimize SVGs with [SVGOMG](https://jakearchibald.github.io/svgomg/). Keep the `viewBox` attribute for best Android results.
- Convert SVG to React Native components with [SVGR](https://react-svgr.com/playground/?native=true&typescript=true).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |