🎛️ 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[]

DC17 · Custom file-type icons (fileIcons + fileIconCallback)

Each row's icon resolves from the file's category by default (Lucide glyphs). Override per extension or per category with the fileIcons map, or take full control with fileIconCallback. Values are any HTML string — this demo mixes an inline SVG (.psd), an <img> (.fig), and emoji (.sketch, the archive category, and the callback).

⚠️ Icon values are inserted as raw HTML (innerHTML) and are NOT sanitized. Only pass markup you control — never untrusted / user-supplied strings.

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

// Keyed by EXTENSION (leading dot optional, case-insensitive) OR CATEGORY.
// Extension keys win over category keys, which win over the built-in icon.
el.fileIcons = {
  psd:     '<svg …>…</svg>',            // extension → inline SVG
  fig:     '<img src="…" alt="">',            // extension → <img>
  sketch:  '💎',                              // extension → emoji
  archive: '📦',                              // whole CATEGORY → emoji
}

// Consulted BEFORE the map. Return HTML to use it, or null to fall through.
el.fileIconCallback = (file) =>
  /^invoice/i.test(file.name) ? '🧾' : null