Document SVG support (#134)

Shopify · Jan 21, 2022 · de7d7d3 · de7d7d3
1 parent b4b5e11
commit de7d7d3
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 4 deletions.
diff --git a/docs/docs/image-svg.md b/docs/docs/image-svg.md
@@ -1,11 +1,11 @@
 ---
 id: image-svg
-title: Image SVG
+title: SVG Images
 sidebar_label: SVG
 slug: /images-svg
 ---
 
-Draw an SVG
+Draw an SVG (see [SVG Support](#svg-support)).
 
 | Name      | Type      |  Description                                                  |
 |:----------|:----------|:--------------------------------------------------------------|
@@ -39,3 +39,100 @@ const ImageSVGDemo = () => {
   );
 };
 ```
+
+You can also use an inlined string as SVG (using `Skia.SVG.MakeFromString`:
+
+```tsx twoslash
+import React from "react";
+import { Canvas, ImageSVG, Skia } from "@shopify/react-native-skia";
+
+const svg = Skia.SVG.MakeFromString(
+  `<svg viewBox='0 0 290 500' xmlns='http://www.w3.org/2000/svg'>
+    <circle cx='31' cy='325' r='120px' fill='#c02aaa'/>
+  </svg>`
+)!;
+
+export const SVG = () => {
+  return (
+    <Canvas style={{ flex: 1 }}>
+      <ImageSVG
+        source={svg}
+        x={0}
+        y={0}
+        width={290}
+        height={500}
+      />
+    </Canvas>
+  );
+};
+```
+
+## SVG Support
+
+We use the [SVG module from Skia](https://github.com/google/skia/tree/main/modules/svg).
+As far as we tested it, we found its capabilities and compliance level to be strong.
+We expect most SVG files correctly out of the box.
+However, please be aware of some of the quirks below when using it.
+If your SVG doesn't render correctly and you've considered all the items below, please file [an issue](https://github.com/Shopify/react-native-skia/issues/new).
+
+### Using SVGO
+
+Using [SVGO](https://github.com/svg/svgo) to normalize the SVG file helps a lot. You can use it online [here](https://jakearchibald.github.io/svgomg/). For instance, it can normalize CSS style attributes that contain transformations to the proper transform property.
+
+### RGBA Colors
+
+The RGBA color syntax is not supported. Instead, you need to use the `fill-opacity` and `stroke-opacity` attributes. Consider the example below.
+
+```xml
+<circle
+  r="10"
+  cx="10"
+  cy="10"
+  fill="rgba(100, 200, 300, 0.5)"
+  stroke="rgba(100, 200, 300, 0.8)"
+/>
+```
+
+Would need to be rewritten as:
+
+```xml
+<circle
+  r="10"
+  cx="10"
+  cy="10"
+  fill="rgb(100, 200, 300)"
+  fill-opacity="0.5"
+  stroke="rgb(100, 200, 300)"
+  stroke-opacity="0.8"
+/>
+```
+
+There is also the `opacity` attribute that applies to both the `fill` and `stroke` attributes.
+
+### Font Familly
+
+When rendering your SVG with Skia, all fonts available in your app are also available to your SVG. However, the way you can set the `font-family` attribute is not flexible at all.
+This is [a known issue](https://github.com/google/skia/blob/main/modules/svg/src/SkSVGText.cpp#L77) in the SVG Skia module. 
+The fallback syntax won't work:
+```jsx
+// Here we assume that if MyFont is not available, it will default to monospace.
+// This won't work.
+// If MyFont is available, this syntax will be accepted.
+<text font-family="MyFont, monospace" />
+```
+
+The single quote syntax won't work either.
+```jsx
+// This won't work
+<text font-family="'MyFont', monospace" />
+// This will work if MyFont is available in the app
+<text font-family="'MyFont', monospace" />
+```
+
+### Inlined SVGs
+
+Some SVGs contain inlined SVGs via the `<image>` or `<feImage>` elements. This is not supported.
+
+### Fallbacks
+
+Some SVG with issues display nicely in the browser because they are so tolerant of errors. We found that the Skia SVG module is much less forgiving.
diff --git a/example/src/Examples/API/SVG.tsx b/example/src/Examples/API/SVG.tsx
@@ -1,11 +1,15 @@
 import React from "react";
 import { Dimensions } from "react-native";
-import { Canvas, ImageSVG, useSVG } from "@shopify/react-native-skia";
+import { Canvas, ImageSVG, Skia, useSVG } from "@shopify/react-native-skia";
 
 const { width, height } = Dimensions.get("window");
 
+const svg = Skia.SVG.MakeFromString(
+  "<svg width='290' height='500' viewBox='0 0 290 500' xmlns='http://www.w3.org/2000/svg'><circle cx='31' cy='325' r='120px' fill='#c02aaa'/></svg>"
+);
+
 export const SVG = () => {
-  const svg = useSVG(require("./tiger.svg"));
+  // const svg = useSVG(require("./tiger.svg"));
   if (svg === null) {
     return null;
   }