Docs › Web component

The <excel-82> web component: attributes and events

Attributes, JS properties and methods, states, events, CSS variables and ::part() of the drag-and-drop form component.

<excel-82> is a web component with a drop zone and file button, a summary (name, format, columns, rows), a pass/fail badge, the list of errors and warnings, a preview table, a template download and an upload progress bar. It uses Shadow DOM, works with the keyboard and announces results with aria-live.

<excel-82 headers="Name,Phone,Amount" min-rows="1" accept="xlsx,xls,csv"
          preview-rows="5" template-download="xlsx"></excel-82>

Attributes

Changing a rule attribute re-checks the file already chosen.

Attribute	Meaning
`headers`	Expected headers, comma separated or a JSON array. Order matters; compared after NFC normalization
`columns`	Number of columns
`min-rows`, `max-rows`	Range for the number of data rows
`sheet`	Sheet name or zero-based index (default: the first sheet)
`header-row`	Header row number (1-based, default 1)
`accept`	Allowed formats, comma separated from `xlsx,xls,csv`
`max-size`	Maximum size in bytes (default 52428800 = 50 MB)
`strict-warnings`	Treat warnings (personal data, macros, hidden content, merged headers, extension mismatch, ragged rows, duplicate headers, cell errors) as errors
`template`	URL of a template file; header and column rules come from it. Attribute rules win when both are given
`locale`	`en` (default), `ko`
`preview-rows`	Preview rows (default 5, 0 hides the preview)
`template-download`	`csv` or `xlsx`: shows a template download button (when `headers` is set)
`name`, `required`, `disabled`	Form integration
`upload`	URL to upload to. No upload without it
`upload-as`	`file` (default, multipart) or `json` (`{ fileName, sheet, columns, rows }`)
`upload-field`	Multipart field name (default `file`)
`upload-auto`	Default `true`. With `false`, the upload runs on form submit and the form is submitted again
`telemetry`	`off` turns off usage statistics

JS properties and methods

.file, .result (the check result), .info (the inspect result), .state, .rules (set from JS to replace the attribute rules), .uploadResponse, .check(file), .upload(), .reset(), and for form validation .form, .validity, .validationMessage, .checkValidity(), .reportValidity().

const x = document.querySelector('excel-82');
x.addEventListener('check', (e) => {
  console.log(e.detail.ok, e.detail.errors);   // the check result
});
x.rules = { headers: ['Name', 'Amount'], rows: { min: 1 } }; // replaces the attribute rules
await x.check(file);   // check a file from code
x.reset();

States

idle → checking → invalid | valid → uploading → uploaded | uploadfailed. Form submission is blocked when required has no file, and in the invalid, uploading and uploadfailed states. More in Upload and forms.

Events

All of them bubble and are composed.

Event	When	`detail`
`check`	A check finished	The check result
`beforeupload`	Right before an upload (cancel with `preventDefault()`)	`{ file, init }`; put auth headers in `init.headers`
`uploadprogress`	During the upload	`{ loaded, total }`
`uploaded`	Upload finished	`{ status, response }`
`uploaderror`	Upload failed	`{ status?, error }`

Styling

CSS variables --e82-accent, --e82-error, --e82-warn, --e82-bg, --e82-fg, --e82-border, --e82-radius. It follows dark mode (prefers-color-scheme).

::part(): drop, label, choose, input, summary, status, issues, preview, template, progress, retry, notice.

excel-82 { --e82-accent: #0b5fff; --e82-radius: 12px; }
excel-82::part(drop) { padding: 32px; }