> 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 settings are 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`

A function that 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 is an object containing the query options. See below for the detailed type `FetchAlbumItemsOptions`Please refer to it.

**Return value**

* `Promise<AlbumItemResponse\[]>`

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

**Error**

| Error code                | Trigger 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('The 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('The 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:

* typesArray<'PHOTO' | 'VIDEO'>

  A list of media types to import. `'PHOTO'`(photo), `'VIDEO'`You can choose from (video). If not specified, only photos are imported.
* **maxCountnumber** · `10`

  The maximum number of items to import.
* **maxWidthnumber** · `1024`

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

  Whether to return the image's `dataUri`as a Base64 string.

**`AlbumItemResponse`**

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

Properties:

* idstring

  This is the item's unique ID.
* **data** · `Uristring`

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

  This is the media type.

***

### 2. Fetch album

**SDK function:** `fetchAlbumPhotos`

{% hint style="info" %}
**A new version is available**

`fetchAlbumPhotos`Only photos are supported. If you need to select photos and videos together or need finer control, [`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)please use it.
{% endhint %}

A function that loads the photo list from the user's album. You can set the maximum number and resolution.

**Signature**

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

**Parameters**

* **options** · Required

  It is an object containing the query options.

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

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

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

    Set whether to return the image in Base64 format.

**Return value**

* `Promise<ImageResponse\[]>`

  Returns an array containing the album photo's unique ID and data URI.

**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 permission to read album');
    }
  }
}
```

{% 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 permission to read album
      }
    }
  };

  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 permission to read album
      }
    }
  };

  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.