List files
You can either list all objects uploaded under a given path or opt to receive a paginated list of objects.
list
1import { list } from 'aws-amplify/storage';2
3try {4 const result = await list({5 path: 'public/photos/',6 // Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`7 });8} catch (error) {9 console.log(error);10}
1import { list } from 'aws-amplify/storage';2
3try {4 const result = await list({5 prefix: 'photos/',6 options: {7 accessLevel: 'protected', // defaults to `guest` but can be 'private' | 'protected' | 'guest'8 targetIdentityId: 'xxxxxxx' // the identityId of that user9 // targetIdentityId is needed only it accessLevel is protected10 }11 });12} catch (error) {13 console.log(error);14}
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
1{2 items: [3 {4 path: 'public/photos/123.jpg',5 eTag: '30074401292215403a42b0739f3b5262',6 lastModified: 'Thu Oct 08 2020 23:59:31 GMT+0800 (Singapore Standard Time)',7 size: 1382568 },9 // ...10 ],11}
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:
1function processStorageList(response) {2 let files = [];3 let folders = new Set();4 response.items.forEach((res) => {5 if (res.size) {6 files.push(res);7 // sometimes files declare a folder with a / within then8 let possibleFolder = res.path.split('/').slice(0, -1).join('/');9 if (possibleFolder) folders.add(possibleFolder);10 } else {11 folders.add(res.path);12 }13 });14 return { files, folders };15}
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:
1function processStorageList(response) {2 const filesystem = {};3 // https://stackoverflow.com/questions/44759750/how-can-i-create-a-nested-object-representation-of-a-folder-structure4 const add = (source, target, item) => {5 const elements = source.split('/');6 const element = elements.shift();7 if (!element) return; // blank8 target[element] = target[element] || { __data: item }; // element;9 if (elements.length) {10 target[element] =11 typeof target[element] === 'object' ? target[element] : {};12 add(elements.join('/'), target[element], item);13 }14 };15 response.items.forEach((item) => add(item.path, filesystem, item));16 return filesystem;17}
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
.
1import { list } from 'aws-amplify/storage';2
3try {4 const response = await list({5 path: 'public/photos/',6 // Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`7 options: {8 listAll: true9 }10 });11 // render list items from response.items12} catch (error) {13 console.log('Error ', error);14}
1import { list } from 'aws-amplify/storage';2
3try {4 const response = await list({5 prefix: 'photos/',6 options: {7 listAll: true8 }9 });10 // render list items from response.items11} catch (error) {12 console.log('Error ', error);13}
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:
1import { list } from 'aws-amplify/storage';2
3const PAGE_SIZE = 20;4let nextToken = undefined;5//...6const loadNextPage = async () => {7 let response = await list({8 path: 'public/photos/',9 // Alternatively, path: ({identityId}) => `protected/${identityId}/photos/`10 pageSize: PAGE_SIZE,11 nextToken: nextToken12 }13 });14 if (response.nextToken) {15 nextToken = response.nextToken;16 } else {17 nextToken = undefined;18 }19 // render list items from response.items20};
1import { list } from 'aws-amplify/storage';2
3const PAGE_SIZE = 20;4let nextToken = undefined;5//...6const loadNextPage = async () => {7 let response = await list({8 key: 'photos/'9 options: {10 pageSize: PAGE_SIZE,11 nextToken: nextToken12 }13 });14 if (response.nextToken) {15 nextToken = response.nextToken;16 } else {17 nextToken = undefined;18 }19 // render list items from response.items20};
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.