0
# Canvas and Views
1

2
Core rendering infrastructure providing canvas components and low-level view access for graphics rendering in React Native Skia.
3

4
## Capabilities
5

6
### Canvas Component
7

8
The main canvas component for rendering Skia graphics with React Native integration.
9

10
```typescript { .api }
11
/**
12
 * Main canvas component for rendering Skia graphics
13
 * @param props - Canvas configuration and children
14
 * @returns JSX canvas element
15
 */
16
function Canvas(props: CanvasProps): JSX.Element;
17

18
interface CanvasProps extends Omit<ViewProps, "onLayout"> {
19
  /** Enable debug mode to show performance metrics */
20
  debug?: boolean;
21
  /** Make canvas opaque for better performance when no transparency needed */
22
  opaque?: boolean;
23
  /** Shared value to receive canvas size updates */
24
  onSize?: SharedValue<SkSize>;
25
  /** Color space for rendering (p3 for wide gamut, srgb for standard) */
26
  colorSpace?: "p3" | "srgb";
27
  /** Ref for accessing canvas methods */
28
  ref?: React.Ref<CanvasRef>;
29
  /** Child components to render */
30
  children?: React.ReactNode;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import React from "react";
38
import { Canvas, Circle, Paint } from "@shopify/react-native-skia";
39

40
// Basic canvas
41
export function BasicCanvas() {
42
  return (
43
    <Canvas style={{ width: 300, height: 300 }}>
44
      <Circle cx={150} cy={150} r={50}>
45
        <Paint color="red" />
46
      </Circle>
47
    </Canvas>
48
  );
49
}
50

51
// Canvas with debug and size tracking
52
export function ConfiguredCanvas() {
53
  const size = useSharedValue({ width: 0, height: 0 });
54
  
55
  return (
56
    <Canvas 
57
      style={{ flex: 1 }} 
58
      debug={true}
59
      opaque={true}
60
      colorSpace="p3"
61
      onSize={size}
62
    >
63
      {/* graphics content */}
64
    </Canvas>
65
  );
66
}
67
```
68

69
### Canvas Reference Methods
70

71
Reference object providing imperative access to canvas operations.
72

73
```typescript { .api }
74
interface CanvasRef {
75
  /** Create a snapshot image of the canvas content */
76
  makeImageSnapshot(rect?: SkRect): SkImage;
77
  /** Asynchronously create a snapshot image of the canvas content */
78
  makeImageSnapshotAsync(rect?: SkRect): Promise<SkImage>;
79
  /** Force the canvas to redraw */
80
  redraw(): void;
81
  /** Get the native view identifier */
82
  getNativeId(): number;
83
  /** Measure the canvas dimensions */
84
  measure(callback: MeasureOnSuccessCallback): void;
85
  /** Measure the canvas position in window coordinates */
86
  measureInWindow(callback: MeasureInWindowOnSuccessCallback): void;
87
}
88

89
// Measurement callback types
90
type MeasureOnSuccessCallback = (
91
  x: number,
92
  y: number,
93
  width: number,
94
  height: number,
95
  pageX: number,
96
  pageY: number
97
) => void;
98

99
type MeasureInWindowOnSuccessCallback = (
100
  x: number,
101
  y: number,
102
  width: number,
103
  height: number
104
) => void;
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
import React, { useRef } from "react";
111
import { Canvas, CanvasRef } from "@shopify/react-native-skia";
112

113
function CanvasWithSnapshot() {
114
  const canvasRef = useRef<CanvasRef>(null);
115
  
116
  const takeSnapshot = () => {
117
    if (canvasRef.current) {
118
      const image = canvasRef.current.makeImageSnapshot();
119
      // Use the image...
120
    }
121
  };
122
  
123
  const takeAsyncSnapshot = async () => {
124
    if (canvasRef.current) {
125
      const image = await canvasRef.current.makeImageSnapshotAsync();
126
      // Use the image...
127
    }
128
  };
129
  
130
  return (
131
    <Canvas ref={canvasRef} style={{ width: 300, height: 300 }}>
132
      {/* content */}
133
    </Canvas>
134
  );
135
}
136
```
137

138
### Canvas Hooks
139

140
Utility hooks for working with canvas components.
141

142
```typescript { .api }
143
/**
144
 * Hook to create a typed canvas reference
145
 * @returns Ref object for Canvas component
146
 */
147
function useCanvasRef(): RefObject<CanvasRef>;
148

149
/**
150
 * Hook to get canvas size with automatic updates
151
 * @param userRef - Optional existing canvas ref to use
152
 * @returns Object with ref and size state value
153
 */
154
function useCanvasSize(userRef?: RefObject<CanvasRef>): {
155
  ref: RefObject<CanvasRef>;
156
  size: SkSize;
157
};
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { useCanvasRef, useCanvasSize } from "@shopify/react-native-skia";
164

165
function ComponentWithCanvasHooks() {
166
  // Simple ref hook
167
  const canvasRef = useCanvasRef();
168
  
169
  // Size tracking hook
170
  const { ref: sizeRef, size } = useCanvasSize();
171
  
172
  return (
173
    <Canvas ref={canvasRef} style={{ width: 300, height: 300 }}>
174
      {/* Use size.value.width and size.value.height */}
175
    </Canvas>
176
  );
177
}
178
```
179

180
### Offscreen Rendering
181

182
Functions for rendering React elements to images and pictures outside of the main canvas.
183

184
```typescript { .api }
185
/**
186
 * Render a React element to a Skia picture
187
 * @param element - React element containing Skia components
188
 * @param bounds - Optional bounds for the picture
189
 * @returns Promise resolving to SkPicture
190
 */
191
function drawAsPicture(
192
  element: ReactElement,
193
  bounds?: SkRect
194
): Promise<SkPicture>;
195

196
/**
197
 * Render a React element to a Skia image
198
 * @param element - React element containing Skia components
199
 * @param size - Size of the output image
200
 * @returns Promise resolving to SkImage
201
 */
202
function drawAsImage(
203
  element: ReactElement,
204
  size: SkSize
205
): Promise<SkImage>;
206

207
/**
208
 * Convert a Skia picture to an image
209
 * @param picture - Source SkPicture to convert
210
 * @param size - Size of the output image
211
 * @returns SkImage
212
 */
213
function drawAsImageFromPicture(
214
  picture: SkPicture,
215
  size: SkSize
216
): SkImage;
217

218
/**
219
 * Check if currently running on the main JavaScript thread
220
 * @returns Boolean indicating main thread status
221
 */
222
function isOnMainThread(): boolean;
223
```
224

225
**Usage Examples:**
226

227
```typescript
228
import { drawAsImage, drawAsPicture, Skia } from "@shopify/react-native-skia";
229

230
async function createOffscreenImage() {
231
  // Create image from React element
232
  const image = await drawAsImage(
233
    <Circle cx={50} cy={50} r={25}>
234
      <Paint color="blue" />
235
    </Circle>,
236
    { width: 100, height: 100 }
237
  );
238
  
239
  return image;
240
}
241

242
async function createPicture() {
243
  // Create reusable picture
244
  const picture = await drawAsPicture(
245
    <Rect x={0} y={0} width={100} height={100}>
246
      <Paint color="green" />
247
    </Rect>
248
  );
249
  
250
  // Convert to image when needed
251
  const image = drawAsImageFromPicture(picture, { width: 100, height: 100 });
252
  
253
  return { picture, image };
254
}
255
```
256

257
### SkiaPictureView
258

259
Lower-level view component for rendering SkPicture objects directly.
260

261
```typescript { .api }
262
/**
263
 * Lower-level view component for rendering SkPicture objects
264
 */
265
class SkiaPictureView extends React.Component<SkiaPictureViewProps> {
266
  /** Create an image snapshot of the view content */
267
  makeImageSnapshot(rect?: SkRect): SkImage;
268
  /** Request the view to redraw */
269
  redraw(): void;
270
  /** Get the native view identifier */
271
  readonly nativeId: number;
272
}
273

274
interface SkiaPictureViewProps extends SkiaPictureViewNativeProps {
275
  /** Rendering mode for the picture view */
276
  mode?: "default" | "continuous";
277
}
278

279
interface SkiaPictureViewNativeProps {
280
  /** Enable debug mode */
281
  debug?: boolean;
282
  /** Optional size change callback */
283
  onSize?: (size: SkSize) => void;
284
  /** Make view opaque for performance */
285
  opaque?: boolean;
286
}
287
```
288

289
### View API Interface
290

291
Low-level API interface for direct view manipulation.
292

293
```typescript { .api }
294
interface ISkiaViewApi {
295
  /** Set a JSI property on a native view */
296
  setJsiProperty<T>(nativeId: number, name: string, value: T): void;
297
  /** Request a view to redraw */
298
  requestRedraw(nativeId: number): void;
299
  /** Create an image snapshot of a view */
300
  makeImageSnapshot(nativeId: number, rect?: SkRect): SkImage;
301
  /** Asynchronously create an image snapshot of a view */
302
  makeImageSnapshotAsync(nativeId: number, rect?: SkRect): Promise<SkImage>;
303
  /** Get the size of a view */
304
  size(nativeId: number): SkSize;
305
}
306
```
307

308
## Core Types
309

310
```typescript { .api }
311
// Base view properties
312
interface NativeSkiaViewProps {
313
  debug?: boolean;
314
  opaque?: boolean;
315
}
316

317
interface SkiaBaseViewProps extends NativeSkiaViewProps {
318
  onSize?: SharedValue<SkSize>;
319
}
320

321
// Size and measurement types
322
interface SkSize {
323
  width: number;
324
  height: number;
325
}
326

327
interface SkRect {
328
  x: number;
329
  y: number;
330
  width: number;
331
  height: number;
332
}
333
```