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
};

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.