---
name: "snapshot"
mode: "api"
versionRequirements:
  - { name: "Base Library", version: "2.23.0" }
title: "snapshot - Page Element Screenshot"
---

## snapshot

> [VERSION] Base Library >= 2.23.0

### Description

Capture a screenshot of an element on the page

### Parameters

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `params` | `Object` | Yes | Screenshot parameters |

##### snapshot.params properties

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `selector` | `string` | No | - | Element selector; supports ID or class selectors |
| `backgroundColor` | `string` | No | - | Screenshot background color; if not provided, png defaults to transparent and jpeg defaults to white |
| `format` | `"png" \| "jpeg"` | No | - | Image format; supports only `png` or `jpeg` |
| `quality` | `number` | No | - | Image quality, range `0~1`; applies only to `jpeg` |
| `foreignObjectRendering` | `boolean` | No | - | Whether to enable foreignObjectRendering |
| `success` | `(res: SnapshotSuccessResult) => void` | No | - | Success callback for screenshot; returns image Base64, temporary path, and dimensions |
| `fail` | `(error: SnapshotFailResult) => void` | No | - | Screenshot failure callback; returns the error message errMsg |
| `complete` | `(res: Partial) => void` | No | - | Completion callback (triggered on both success and failure) |


##### Partial properties

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `imageData` | `string` | No | - | Base64-encoded image data; can be used for upload |
| `tempImagePath` | `string` | No | - | Temporary file path, valid only on real devices; can be used to save to the photo album |
| `width` | `number` | No | - | Image width |
| `height` | `number` | No | - | Image height |
| `errMsg` | `string` | No | - | Error message |


### Return Value

None


### Referenced Types

##### `interface` SnapshotSuccessResult

| Property | Type | Description |
| --- | --- | --- |
| `imageData` | `string` | Base64-encoded image data; can be used for upload |
| `tempImagePath` | `string` | Temporary file path, valid only on real devices; can be used to save to the photo album |
| `width` | `number` | Image width |
| `height` | `number` | Image height |

##### `interface` SnapshotFailResult

| Property | Type | Description |
| --- | --- | --- |
| `errMsg` | `string` | Error message |


### Examples

#### Capture a screenshot of a page element

```js
Page({
  onCapture() {
    ty.snapshot({
      selector: '#capture-area',
      format: 'png',
      success(res) {
        console.log('Screenshot successful', res.tempImagePath);
        console.log('Width/height', res.width, res.height);
      },
      fail(err) {
        console.error('Screenshot failed', err.errMsg);
      },
    });
  },
});
```

#### Capture a screenshot with specified format and quality

```js
Page({
  onCapture() {
    ty.snapshot({
      selector: '.card',
      format: 'jpeg',
      quality: 0.8,
      backgroundColor: '#ffffff',
      success(res) {
        console.log('JPEG screenshot', res.imageData.substring(0, 50));
      },
    });
  },
});
```


## Notes

> Due to the complexity of page styles, screenshot results may vary. If you encounter such issues, try adjusting the page styles.

## Known Issues

1. `ty.snapshot` may fail to capture screenshots correctly for complex layouts or on iOS 18. In such cases, use canvas to draw the content, convert it to base64, and then save the image.