Name:
interface
Value:
Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated May 2, 2024

List files

You can either list all objects uploaded under a given path or opt to receive a paginated list of objects.

list

import { list } from 'aws-amplify/storage';
try {
const result = await list({
path: 'public/photos/',
// Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`
});
} catch (error) {
console.log(error);
}
import { list } from 'aws-amplify/storage';
try {
const result = await list({
prefix: 'photos/',
options: {
accessLevel: 'protected', // defaults to `guest` but can be 'private' | 'protected' | 'guest'
targetIdentityId: 'xxxxxxx' // the identityId of that user
// targetIdentityId is needed only it accessLevel is protected
}
});
} catch (error) {
console.log(error);
}

Note the trailing slash / - if you had requested list({ path : 'public/photos' }) it would also match against files like public/photos123.jpg alongside public/photos/123.jpg.

The format of the response will look similar to the below example

{
items: [
{
path: 'public/photos/123.jpg',
eTag: '30074401292215403a42b0739f3b5262',
lastModified: 'Thu Oct 08 2020 23:59:31 GMT+0800 (Singapore Standard Time)',
size: 138256
},
// ...
],
}

Manually created folders will show up as files with a size of 0, but you can also match keys against a regex like file.key.match(/\.[0-9a-z]+$/i) to distinguish files from folders. Since "folders" are a virtual concept in S3, any file may declare any depth of folder just by having a / in its name. If you need to list all the folders, you'll have to parse them accordingly to get an authoritative list of files and folders:

function processStorageList(response) {
let files = [];
let folders = new Set();
response.items.forEach((res) => {
if (res.size) {
files.push(res);
// sometimes files declare a folder with a / within then
let possibleFolder = res.path.split('/').slice(0, -1).join('/');
if (possibleFolder) folders.add(possibleFolder);
} else {
folders.add(res.path);
}
});
return { files, folders };
}

If you need the files and folders in terms of a nested object instead (for example, to build an explorer UI), you could parse it recursively:

function processStorageList(response) {
const filesystem = {};
// https://stackoverflow.com/questions/44759750/how-can-i-create-a-nested-object-representation-of-a-folder-structure
const add = (source, target, item) => {
const elements = source.split('/');
const element = elements.shift();
if (!element) return; // blank
target[element] = target[element] || { __data: item }; // element;
if (elements.length) {
target[element] =
typeof target[element] === 'object' ? target[element] : {};
add(elements.join('/'), target[element], item);
}
};
response.items.forEach((item) => add(item.path, filesystem, item));
return filesystem;
}

This places each item's data inside a special __data key.

Access all files

To get a list of all files in your S3 bucket under a specific prefix, you can set listAll to true.

import { list } from 'aws-amplify/storage';
try {
const response = await list({
path: 'public/photos/',
// Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`
options: {
listAll: true
}
});
// render list items from response.items
} catch (error) {
console.log('Error ', error);
}
import { list } from 'aws-amplify/storage';
try {
const response = await list({
prefix: 'photos/',
options: {
listAll: true
}
});
// render list items from response.items
} catch (error) {
console.log('Error ', error);
}

Paginated file access

If the pageSize is set lower than the total file size, a single list call only returns a subset of all the files. To list all the files with multiple calls, users can use the nextToken flag:

import { list } from 'aws-amplify/storage';
const PAGE_SIZE = 20;
let nextToken = undefined;
//...
const loadNextPage = async () => {
let response = await list({
path: 'public/photos/',
// Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`
pageSize: PAGE_SIZE,
nextToken: nextToken
}
});
if (response.nextToken) {
nextToken = response.nextToken;
} else {
nextToken = undefined;
}
// render list items from response.items
};
import { list } from 'aws-amplify/storage';
const PAGE_SIZE = 20;
let nextToken = undefined;
//...
const loadNextPage = async () => {
let response = await list({
key: 'photos/'
options: {
pageSize: PAGE_SIZE,
nextToken: nextToken
}
});
if (response.nextToken) {
nextToken = response.nextToken;
} else {
nextToken = undefined;
}
// render list items from response.items
};
Note: The range of pageSize can be from 0 - 1000.

List with no prefix (Deprecated)

The usage of the list API without a specified prefix await list() or with an empty string as the prefix await list({ prefix: "" }) is now deprecated and may be removed in the next major version.