🎛️ Display & Composition

DC01 · Display: three orthogonal axes

The visual surface is split into three independent attributes you can combine freely:

• selector-appearance — card · button · minimal · (what the user clicks/drops onto)
• list-appearance — list · detailed · grid · badges · popover · none · (where picked files appear)
• card-size — minimal · compact · big · (density of the card selector)

The legacy single-axis display-mode attribute is still supported as a shorthand — see the bottom of this page.

DC02 · Composable controls (controls + item-controls)

Two Plyr-style allowlists. controls picks which top-level surfaces render; item-controls picks which parts of each file row render. Both are comma-separated; when an attribute is absent everything renders. Toggle the boxes and watch the dropzone recompose live — add a file to see the progress parts animate.

DC03 · Recipes — progress rules in userland

Count- or state-based progress behaviour doesn't need dedicated attributes — compose it from the primitives above plus the change event and auto-upload. Two common asks:

Per-row bars only at 4+ files (count-based)

const dz = document.getElementById('recipe-count')
const LEAN = 'icon,name,size,type,status,action,remove' // no progress

dz.addEventListener('change', () => {
  const want = dz.files.length >= 4 ? null : LEAN
  // skip no-op writes; `change` fires on selection changes only, so no loop
  if (dz.getAttribute('item-controls') === want) return
  want === null ? dz.removeAttribute('item-controls')
                : dz.setAttribute('item-controls', want)
})

Global strip only after upload starts (state-based)

<web-dropzone auto-upload="false" ...></web-dropzone>

// files added → pending → global strip hidden (hasActivity = false)
startBtn.addEventListener('click', () => dz.uploadAll())
// upload starts → strip appears on its own

DC04 · Selector Appearance (selector-appearance)

Four visual entry points for picking files.

DC05 · List Appearance (list-appearance)

How the picked files are presented. Six options ranging from a simple vertical list to badge-style pills or a hidden popover.

DC06 · Grid tuning — live controls

Grid mode is almost entirely CSS-variable driven. Drop a few images below, then move the sliders to reshape the grid in real time. The panel writes the same --dz-* custom properties you'd set in your own CSS — the live readout is copy-pasteable.

Switch grid-layout to natural for a justified photo gallery: mixed portrait/landscape images share one row height (--dz-preview-row-height) and keep their own aspect ratio — nothing cropped or stretched. In uniform layout, object-fit chooses crop (cover) vs. fit (contain). Set grid-status="overlay" and let a file finish uploading to see the light veil + big centred check/error glyph.

DC07 · Card Size (card-size)

Density variants for the card selector. Only meaningful when selector-appearance="card".

DC08 · Files-Inside Layout (files-inside)

Render the file list inside the dropzone area instead of below it. Useful when vertical space is constrained or when you want a unified container look.

DC09 · Common combinations

Mixing the three axes covers the patterns users actually want — toolbars, attachment fields, marketing landings, and more.

DC10 · Summary Template (summary-template)

When list-appearance="popover" the summary line supports {count} and {size} placeholders — quick customization without writing JS. For richer summaries (pluralization, badges) use renderSummaryCallback; see Structural Rendering.

DC11 · Popover Placement (popover-placement)

Positioning uses Floating UI, so it auto-flips on viewport collisions. The attribute sets the preferred initial placement.

DC12 · Legacy display-mode shorthand

The original single-axis attribute still works as a shorthand. When both are set, the orthogonal attribute wins.

• display-mode="list" → selector-appearance="card" + list-appearance="list"
• display-mode="detailed" → card + detailed
• display-mode="grid" → card + grid
• display-mode="compact" → card + popover

DC13 · Single vs Multiple

The multiple attribute defaults to true. Set multiple="false" to lock to a single file (subsequent drops replace the existing selection).

DC14 · Accept Patterns

The accept attribute uses the same syntax as the native <input type="file">: comma-separated MIME types, MIME wildcards, or file extensions.

DC15 · Disabled State

The disabled attribute follows HTML convention: presence enables it, ="false" overrides.

DC16 · Programmatic API

Methods and events let you drive the dropzone from your own code.

(none yet — drop or pick a file)

const el = document.getElementById('api-demo')

el.addEventListener('file-added',     e => console.log('added',    e.detail))
el.addEventListener('file-removed',   e => console.log('removed',  e.detail))
el.addEventListener('files-rejected', e => console.log('rejected', e.detail))
el.addEventListener('change',         e => console.log('change',   e.detail))

el.addFiles(fileList)        // programmatic add (FileList or File[])
el.removeFile(id)            // remove by FileState.id
el.clear()                   // remove all
const files = el.files       // current FileState[]