Expose additional internals and dispatch state

[lancegliser]

On which framework/platform would you like to see this feature implemented?

React

Which UI component is this feature-request for?

Storage

Please describe your feature-request in detail.

There's a number of internals I found inspecting code that would make integration with custom additions for my purposes much easier. I'd like to have them available in state or event callbacks, etc.

The features I want to implement are:

• When only one storage location is available, ensure the user doesn't even have to select it and never leaves it.
• After creating a folder, or uploading a new folder, include 'View' button action in the success message
  • I'd like to be able to add other custom actions as well, like 'Process' that receives the state details so they can automatically kick off actions against the uploaded folder.
• Context menu
  • I'd like to add my own context items, potentially enabled or disabled by selections and receiving that state when the action is clicked.
  • I'm promoting some items out of the context menu (like Upload)
  • I'm adding my own promoted items (like Process)

Please describe a solution you'd like.

Here's my current work around. If we could get these into easily viewed controlled mode state, or other callbacks it would be lovely.

Based on everything we've worked through in this session:

---

Amplify StorageBrowser internals we work around

1. Selected items (locationItems / dataItems)

Not exposed: Checkbox selection state lives in an internal locationItemsDispatch store. onValueChange only carries { actionType, location }.
Our workaround: StorageBrowserDataTable scans rows for checked=true checkbox cells on every render and derives selectedItems in context via SELECTED_ITEMS_CHANGED.

---

2. Action exit internal cleanup (RESET_FILE_ITEMS)

Not exposed: onActionExit on each view dispatches two internal stores — RESET_ACTION_TYPE (store) and RESET_FILE_ITEMS (fileItemsDispatch). Only the first propagates externally via onValueChange. Calling setStorageBrowserValue({ actionType: undefined }) from outside skips RESET_FILE_ITEMS.
Our workaround: Success message renders the real storageBrowser.StorageBrowser.UploadView.Exit / CreateFolderView.Exit composable so Amplify runs its own cleanup. postExitNavigationRef holds the target path and onStorageBrowserValueChange applies it once Amplify's exit event propagates externally.

---

3. useControlsContext / onActionExit not exported

Not exposed: The controls context hook (which gives access to onActionExit, onActionSelect, etc.) is internal. ActionExitControl composable is attached to view objects but not exported from @aws-amplify/ui-react-storage/browser.
Our workaround: Access exit composables via storageBrowser.StorageBrowser.UploadView.Exit and CreateFolderView.Exit (they are attached to the view objects, not independently exported).

---

4. Transient empty location on delete exit

Not exposed/undocumented: When exiting DeleteView, Amplify intermittently emits { actionType: undefined, location: undefined } instead of preserving the current location.
Our workaround: In onStorageBrowserValueChange, when transitioning out of delete with an empty location, we preserve current.location to prevent the user being dropped to the location-selection screen.

---

5. Empty path on single-location action transitions

Not exposed/undocumented: When Amplify emits CHANGE_ACTION_TYPE for upload, createFolder, or delete in single-location mode, the emitted location.path is sometimes "" even when the user is already navigated into a subfolder.
Our workaround: In onStorageBrowserValueChange, when entering one of those actions with path === "" but current.location.path is non-empty, we preserve the current path.

---

6. No onExit callback contract in createStorageBrowser options

Not exposed at the right level: onExit exists as a prop on the standalone view components (UploadView, CreateFolderView) but is not available via createStorageBrowser's options object, so there's no clean way to hook navigation post-exit without rendering the composables directly.
Our workaround: Combine the real Exit composable rendering (#2, #3) with the postExitNavigationRef pattern to sequence navigation after internal cleanup.

---

Summary table

Gap	Workaround location
Selected items state	StorageBrowserDataTable row scan → SELECTED_ITEMS_CHANGED
RESET_FILE_ITEMS on exit	Render real UploadView.Exit / CreateFolderView.Exit composable
useControlsContext not exported	Access via storageBrowser.StorageBrowser.*View.Exit
Delete exit drops location	onStorageBrowserValueChange null-location guard
Empty path on action transition	onStorageBrowserValueChange empty-path preservation
No onExit in createStorageBrowser options	postExitNavigationRef + composable exit rendering

We love contributors! Is this something you'd be interested in working on?

• 👋 I may be able to implement this feature request.
• ⚠️ This feature might incur a breaking change.

[bobbor]

hey @lancegliser

It looks like you are a very intense user of the StorageBrowser. And it is incredible to see what you have achieved already.

I agree with you by marking this as feature request. It adds a bunch of really useful functionality to the storage browser.

We will plan this into one of our upcoming sprints and will let you know, when we have more news

[lancegliser]

Hi again. I'm back with a new analysis and ask! Some of my users have dense upload folders. I was able to reproduce a lack of loading visualization using my own code base as a test file selection (67k+ files). It's not reasonable, but illustrative.

Intermixing my own code and concerns here, but it points out where I have no access:

1. StorageBrowserAddFolder.tsx dispatches UPLOAD_SOURCE_CHANGED, then calls Amplify’s onAddFolder.
2. Amplify’s upload view maps that to onSelectFiles('FOLDER') in UploadViewProvider.mjs:68-72.
3. useUploadView.mjs:40-42 dispatches SELECT_FILES.
4. FileItemsProvider handles SELECT_FILES by calling handleFileSelect(...) in context.mjs:22-25.
5. useFileSelect sets hidden input props, then an effect calls ref.current?.click() in FileSelect.mjs:44-47. That is the launch point for the native file/folder picker. The browser’s “Upload ##,### files to this site?” prompt happens inside that browser-owned flow.

• There's a solid 4 second delay from action to message. This is first place I'd like hooks into, but it's secondary priority.

6. If the user accepts, the hidden input emits onChange; FileSelect.mjs:54-58 calls onSelect([...event.target.files]).
7. FileItemsProvider immediately runs resolveFiles(nextFiles, validateFile) in context.mjs:16-20.
8. resolveFiles synchronously calls validateFile(file) for every file in utils.mjs:12-22.

• This can result in up to 22 seconds of non-response. This is second place I'd like hooks into, and my priority.

9. Our wrapper is useStorageBrowser.tsx, so that is the first local code that proves the user accepted and validation has begun.
10. After validation, Amplify converts valid files into upload tasks; useUploadView.mjs:25-30 derives items/tasks/statusCounts.

Important constraint: with the public createStorageBrowser API, there is no reliable “user accepted folder upload prompt” hook before validateFile. The browser prompt is between input.click() and input.onChange, and Amplify’s useFileSelect only calls us when files exist. If the user cancels, there is no onChange payload and no validateFile.

useFileItems/useUploadView; exist in node_modules, but they are not exported from @aws-amplify/ui-react-storage/browser, so it would be brittle.

For now, I'm going to rig up an immediate and trailing debounce side effect inside validateFile to provide coverage there at least.

Edit: Spoke too soon.

React is locked up during validateFile loop due to the sync nature.

The final implementation works around Amplify’s synchronous validateFile loop by starting UI feedback before validation begins, using browser/file-picker boundary signals instead of waiting for file count resolution.

Flow:

• UPLOAD_SOURCE_CHANGED no longer starts loading directly. It only marks a ref: “the native file picker is probably open.”
• When the browser returns from the picker via window.focus or document.visibilitychange === 'visible', we start provisional state.isFileValidationPending for 5s.
• If Amplify’s hidden file input emits change with selected files, we also start that same provisional 5s pending window.
• If the hidden file input emits cancel, we clear pending immediately.
• Once any validateFile call happens, useStorageBrowser calls onFileValidationActivity; the provider treats that as real validation and switches to a short 300ms idle timeout.
• Every later validateFile call resets the 300ms timer.
• When there is no validation activity for 300ms, pending ends.

The ideal product/API improvement would be an upstream callback around file selection, for example onFileSelectionStart, onFileSelectionCancel, onFilesSelected, and async/chunked validation support so the UI can paint and update progress during huge folder validation.