> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/permission/album.md).

# Album

{% hint style="info" %}
**Permission setup is required**

`fetchAlbumItems`You need to set album permissions before using it. Please check the permission setup guide first.
{% endhint %}

***

### 1. Select album media

**SDK function:** `fetchAlbumItems`

This function selects and imports photos and videos from the user's album. You can select photos and videos at the same time, and if the user cancels the selection, an empty array `[]`returns null.

**Signature**

```typescript
function fetchAlbumItems(options?: FetchAlbumItemsOptions): Promise<AlbumItemResponse[]>;
```

**Parameters**

* **options** · `FetchAlbumItemsOptions`

  It's an object containing the query options. See below for the detailed type `FetchAlbumItemsOptions`.

**Return value**

* `Promise<AlbumItemResponse[]>`

  Returns the list of selected media. If the user cancels, returns an empty array.

**Error**

| Error code                | Condition                                       |
| ------------------------- | ----------------------------------------------- |
| `NOT_ALLOWED`             | When album access is not allowed                |
| `INVALID_REQUEST`         | When the request parameters are invalid         |
| `INVALID_DATA`            | When the media data is invalid                  |
| `UNSUPPORTED_APP_VERSION` | When the Toss app version is lower than 5.261.0 |

**Example**

{% tabs %}
{% tab title="React" %}

```tsx
import { fetchAlbumItems } from '@apps-in-toss/web-framework';

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('Selection was canceled.');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('Album query error:', error.code);
  }
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { fetchAlbumItems } from '@apps-in-toss/framework';

async function pickMedia() {
  try {
    const items = await fetchAlbumItems({
      types: ['PHOTO', 'VIDEO'],
      maxCount: 5,
      base64: true,
    });

    if (items.length === 0) {
      console.log('Selection was canceled.');
      return;
    }

    items.forEach((item) => {
      console.log(item.type, item.id);
    });
  } catch (error) {
    console.error('Album query error:', error.code);
  }
}
```

{% endtab %}
{% endtabs %}

**`FetchAlbumItemsOptions`**

```typescript
interface FetchAlbumItemsOptions {
  types?: AlbumItemType[];
  maxCount?: number;
  maxWidth?: number;
  base64?: boolean;
}
```

Properties:

* types Array<'PHOTO' | 'VIDEO'>

  It's a list of media types to fetch. `'PHOTO'`(photo), `'VIDEO'`You can choose from (video). If omitted, only photos are fetched.
* **maxCount number** · `10`

  The maximum number of items to fetch.
* **maxWidth number** · `1024`

  The maximum width of the image. The unit is pixels.
* **base64 boolean** · `false`

  The image's `dataUri`whether to return it as a Base64 string.

**`AlbumItemResponse`**

```typescript
interface AlbumItemResponse {
  id: string;
  dataUri: string;
  type: AlbumItemType;
}
```

Properties:

* id string

  The unique ID of the item.
* **data** · `Uri string`

  Media data URI. `type`If it is `PHOTO`and `base64` option `true`returns a Base64 string.
* type 'PHOTO' | 'VIDEO'

  It's the media type.

***

### 2. Fetch album

**SDK function:** `fetchAlbumPhotos`

{% hint style="info" %}
**There's a new version**

`fetchAlbumPhotos`only supports photos. If you need to select photos and videos together or need finer control, please use [`fetchAlbumItems`](#_1-%EC%95%A8%EB%B2%94-%EB%AF%B8%EB%94%94%EC%96%B4-%EC%84%A0%ED%83%9D%ED%95%98%EA%B8%B0).
{% endhint %}

This function loads a list of photos from the user's album. You can set the maximum count and resolution.

**Signature**

```typescript
function fetchAlbumPhotos(options: { maxCount: number; maxWidth: number; base64: boolean }): Promise<ImageResponse[]>;
```

**Parameters**

* **options** · Required

  It's an object containing the query options.

  * **options.maxCount** · `number`

    The maximum number of photos to fetch.
  * **options.maxWidth** · `number`

    The maximum width of the photos. The unit is pixels.
  * **options.base64** · `boolean`

    Sets whether to return the image in Base64 format.

**Return value**

* `Promise<ImageResponse[]>`

  Returns an array containing the unique IDs and data URIs of album photos.

**Example**

{% tabs %}
{% tab title="Web (JS)" %}

```js
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError } from '@apps-in-toss/web-framework';

async function handleFetchAlbumPhotos() {
  try {
    const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
    response.forEach((image) => {
      const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
      console.log('Image URI:', imageUri);
    });
  } catch (error) {
    if (error instanceof FetchAlbumPhotosPermissionError) {
      console.log('No album read permission');
    }
  }
}
```

{% endtab %}

{% tab title="Web (React)" %}

```tsx
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // No album read permission
      }
    }
  };

  return (
    <div>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <img src={imageUri} key={image.id} />;
      })}
      <button onClick={handlePress}>Fetch album</button>

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Image, View } from 'react-native';

function AlbumPhotoList() {
  const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);

  const handlePress = async () => {
    try {
      const response = await fetchAlbumPhotos({ base64: true, maxWidth: 360 });
      setAlbumPhotos((prev) => [...prev, ...response]);
    } catch (error) {
      if (error instanceof FetchAlbumPhotosPermissionError) {
        // No album read permission
      }
    }
  };

  return (
    <View>
      {albumPhotos.map((image) => {
        const imageUri = 'data:image/jpeg;base64,' + image.dataUri;
        return <Image source={{ uri: imageUri }} key={image.id} />;
      })}
      <Button title="Fetch album" onPress={handlePress} />
      <Button
        title="Check permission"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="Request permission"
        onPress={async () => {
          const permission = await fetchAlbumPhotos.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/permission/album.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.