PickerOverlay vs PickerInline vs PickerDropPane, Which One to Use

PickerOverlay vs PickerInline vs PickerDropPane, which one to use, is a layout decision rather than a capability one. All three upload the same way, accept the same props and return the same result. What differs is how much of the screen the upload takes and whether the user chose to be there.

All three are running side by side in filestack-snippets, so you can click between them before committing.

Key takeaways

• All three components share the same props and return the same result.
• Pick by layout: modal to interrupt, inline when the upload is the screen, drop pane inside a form.
• Every picker opens on render, so gate it behind your own state.
• PickerDropPane offers no cloud sources, which overrides any layout preference.
• Switching components later is a rename plus a container, so start with the overlay.

The short version

Both packages are needed, since v7 takes filestack-js as a peer dependency:

npm install filestack-react@^7.0.1 filestack-js@^4.0.1

If you are unsure, PickerOverlay is the safe default. It works on any page without a layout budget, and moving to one of the others later is a component rename plus a container.

PickerOverlay

A modal over the current page, with the full source list, the file list and the editing tools.

import { useState } from 'react';
import { PickerOverlay } from 'filestack-react';

export default function UploadButton() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Upload a file</button>
      {open && <PickerOverlay onUploadDone={handleDone} />}
    </>
  );
}

It opens on render. There is no open prop and no imperative .open() call, so the component’s presence in the tree is what shows it. Rendered unconditionally, the modal appears as soon as the page loads.

Close it by setting your own state back in onUploadDone, as above.

It suits attaching a file to a comment, changing an avatar from a settings page, or any flow where the user was doing something else a second ago and expects to return to it.

 

PickerInline

The same picker rendered into the page rather than over it.

import { PickerInline } from 'filestack-react';

<div style={{ height: 500 }}>
  <PickerInline onUploadDone={handleDone} />
</div>

With no children it renders its own container, 500 pixels tall, which is why the wrapper above sets a height rather than leaving it to collapse. It also opens on render, but that is what you want here, since the picker is the content of the screen.

Reach for it on a dedicated upload page, an import step in an onboarding flow, or a media library where browsing cloud sources is the point rather than a detour.

The trade is layout. It occupies real space at a fixed height, so on a short mobile viewport it can push everything else below the fold.

 

PickerDropPane

A drop target and nothing else. No source list, no modal, no browse chrome.

import { PickerDropPane } from 'filestack-react';

<div style={{ height: 220, border: '2px dashed #999', borderRadius: 8 }}>
  <PickerDropPane onUploadDone={handleDone} pickerOptions={{ maxFiles: 10 }} />
</div>

It is the smallest of the three and the one that blends into an existing form. Because it carries no interface of its own beyond the drop area, the surrounding page has to say what belongs there, what the size limit is, and what happens next. The interaction patterns that make a drop area read as one are set out in Drag And Drop File Upload: A Comprehensive Guide.

Use it inside a form the user is already filling in, where a modal would feel like leaving the page and an inline picker would dominate it.

The limitation is that it only accepts drops and clicks through to the local file system. If you need cloud sources, this is not the component.

 

What they share

All three take the same props and differ only in how the picker is displayed.

<PickerInline
  apikey={KEY}
  pickerOptions={{ accept: ['image/*'], maxFiles: 5 }}
  clientOptions={{ security }}
  onUploadDone={handleDone}
  onError={handleError}
/>

In v7 you can lift all of that to FilestackProvider once and leave the components bare. Props set on a component still win, and option objects are shallow-merged with the provider’s as the base, so one screen can differ without the provider changing.

All three also accept a single child element as a custom container. The component clones it, sets the generated DOM id on it, and mounts the picker inside, which is how you keep your own border, radius and shadow. Every prop the three components accept is listed on the React file upload SDK page.

Switching between them

Because the props are identical, switching is a rename plus whatever container the new one needs. That makes it reasonable to start with the overlay and move later, and it makes responsive choices practical:

export default function ResponsivePicker() {
  const isNarrow = useMediaQuery('(max-width: 640px)');
  const Picker = isNarrow ? PickerOverlay : PickerInline;

  return <Picker onUploadDone={handleDone} />;
}

On a phone the modal uses the whole viewport, which is usually better than a 500 pixel inline picker inside a 700 pixel screen.

 

What the choice costs you

Each component has one failure mode that shows up in use rather than in development.

The overlay’s is abandonment. A modal is dismissible, and some proportion of users will open it, look at it and close it without uploading anything. That is fine when the upload is optional and expensive when it is a required step in a flow, because nothing on the underlying page indicates that the step is unfinished. If the upload is mandatory, the page behind the modal has to show that state, and the modal cannot do it for you.

The inline picker’s is layout on small screens. Five hundred pixels is most of a phone viewport, so the submit button underneath it can end up permanently below the fold. Either switch component at a breakpoint or shorten the container and accept the internal scroll.

Discoverability is what catches the drop pane. It renders a drop area and no instructions, so the label around it has to carry them, including that clicking the area opens the local file browser. Getting that label, and the progress and error states around it, to read correctly in a screen reader is covered in file upload accessibility with WCAG and ARIA.

What happens after the pick

The choice of component does not affect the result. All three call onUploadDone with the same PickerResponse, and each uploaded file carries a handle that addresses it on the CDN.

From there the work is the same regardless of which picker collected the file. Transformations are path segments in front of the handle, so a thumbnail is a URL rather than a second dependency. Descriptions for the images the picker collected can be generated the same way, which Generate Alt Text and Metadata from Uploads with Filestack Caption API walks through.

Choosing in about a minute

Three questions settle it.

Did the user come to this screen to upload something? If yes, PickerInline. The picker deserves the space because it is the reason they are here.

Is the upload a step inside a form they are already completing? If yes, PickerDropPane. It adds a drop area without implying they have left the form.

Otherwise, PickerOverlay. An interruption should look like an interruption, and the modal returns them to where they were.

The one input that overrides all three is cloud sources. If people need to pull from Google Drive or a URL, PickerDropPane is out regardless of layout, because it does not offer them.

If none of the three is installed yet, the React file upload tutorial covers the setup that sits underneath all of them.

FAQ

Do the three components upload differently?

No. They share the same props, upload the same way, and call onUploadDone with the same PickerResponse. The only difference is how much of the screen the picker occupies and whether it sits above the page or inside it.

Why does the picker open as soon as the page loads?

Because rendering the component is what opens it. There is no open prop and no .open() call, so a picker rendered unconditionally appears immediately. Gate it behind your own state and close it in onUploadDone.

Can I use PickerDropPane with Google Drive or Dropbox?

No. It accepts drops and clicks through to the local file system only. If cloud sources matter, that rules the drop pane out regardless of how well it would fit the layout.

How hard is it to switch components later?

A rename plus whatever container the new one needs, since the props are identical. That is why starting with the overlay is reasonable, and why swapping components at a breakpoint is practical rather than a rewrite.

 

 

Read More →