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

Choose your framework/language

Page updated May 21, 2024

List file properties

You can list files without having to download all the files. You can do this by using the listFile API from the Amplify Library for Storage. You can also get properties individually for a file using the getProperties API.

List Files

import { list } from 'aws-amplify/storage';
try {
const result = await list({
path: 'photos/',
// Alternatively, path: ({identityId}) => `album/{identityId}/photos/`
});
} catch (error) {
console.log(error);
}

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

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

{
items: [
{
path: "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 Amazon 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.

More list options

OptionTypeDescription
listAllbooleanSet to true to list all files within the specified path
pageSizenumberSets the maximum number of files to be return. The range is 0 - 1000
nextTokenstringIndicates whether the list is being continued on this bucket with a token
useAccelerateEndpointbooleanWhether to use accelerate endpoint.

Read more at Transfer Acceleration

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: 'photos/',
// Alternatively, path: ({ identityId }) => `album/{identityId}/photos/`
pageSize: PAGE_SIZE,
nextToken: nextToken
}
});
if (response.nextToken) {
nextToken = response.nextToken;
} else {
nextToken = undefined;
}
// render list items from response.items
};

Get File Properties

You can also view the properties of an individual file.

import { getProperties } from 'aws-amplify/storage';
try {
const result = await getProperties({
path: "album/2024/1.jpg",
// Alternatively, path: ({ identityId }) => `album/{identityId}/1.jpg`
});
console.log('File Properties ', result);
} catch (error) {
console.log('Error ', error);
}

The properties and metadata will look similar to the below example

{
path: "album/2024/1.jpg",
contentType: "image/jpeg",
contentLength: 6873,
eTag: "\"56b32cf4779ff6ca3ba3f2d455fa56a7\"",
lastModified: Wed Apr 19 2023 14:20:55 GMT-0700 (Pacific Daylight Time) {},
metadata: { owner: 'aws' }
}

More getProperties options

OptionTypeDescription
useAccelerateEndpointbooleanWhether to use accelerate endpoint.

To get the metadata in result for all APIs you have to configure user defined metadata in CORS.

Learn more about how to setup an appropriate CORS Policy.