Skip to content

File input

Preview Available in release assets

Present a native file picker in a resilient shell with space for concise selection and drag-state guidance.

File input primary example

Show code
<div class="thin-field">
  <label for="attachments">Attachments</label>
  <div class="thin-file-input">
    <input id="attachments" name="attachments" type="file" multiple aria-describedby="attachments-hint">
    <span class="thin-file-guidance" id="attachments-hint">Choose files. Drag and drop is available only when the application adds and announces an uploader enhancement.</span>
  </div>
</div>

Each authored example uses the production assets and includes copyable markup.

Single native file

A labelled file picker inside an ordinary multipart form. The application supplies the upload endpoint; the component supplies no upload transport.

Show code
<form action="/attachments" method="post" enctype="multipart/form-data" style="display: grid; gap: 1rem">
  <div class="thin-field" style="overflow-wrap: anywhere">
    <label for="file-single">Attachments</label>
    <div class="thin-file-input">
      <input id="file-single" name="attachments" type="file" aria-describedby="file-single-hint" >
      <small class="thin-file-guidance" id="file-single-hint">Choose files with the native picker. Your application must validate and receive the selected files.</small>
    </div>
  </div>
  <button class="thin-button">Attach file</button>
</form>

Multiple native files

The multiple attribute allows more than one file. Selection remains browser-owned; the library does not replace or simulate a picker.

Show code
<div class="thin-field" style="overflow-wrap: anywhere">
  <label for="file-multiple">Attachments</label>
  <div class="thin-file-input">
    <input id="file-multiple" name="attachments" type="file" aria-describedby="file-multiple-hint" multiple>
    <small class="thin-file-guidance" id="file-multiple-hint">Choose files with the native picker. Your application must validate and receive the selected files.</small>
  </div>
</div>

Accepted image types

accept supplies a picker hint for PNG and JPEG files; it does not validate content. Validate the uploaded files on the server.

Show code
<div class="thin-field" style="overflow-wrap: anywhere">
  <label for="file-images">Attachments</label>
  <div class="thin-file-input">
    <input id="file-images" name="attachments" type="file" aria-describedby="file-images-hint" accept="image/png,image/jpeg">
    <small class="thin-file-guidance" id="file-images-hint">Choose files with the native picker. Your application must validate and receive the selected files.</small>
  </div>
</div>

Anatomy

  • Associated label
  • Native input[type=file]
  • Optional guidance

Variants and sizes

  • Single file — shown above
  • Multiple files — shown above
  • Accepted file types — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Empty, focused and selected filenames

The picker starts empty because HTML cannot prefill a file selection. Tab to it, then choose files with long names to inspect native selection and filename truncation. Automated checks populate only synthetic test files; OS picker and AT review remain separate.

Show code
<section style="max-inline-size: 18rem">
  <div class="thin-field" style="overflow-wrap: anywhere">
    <label for="file-selected">Attachments</label>
    <div class="thin-file-input">
      <input id="file-selected" name="attachments" type="file" aria-describedby="file-selected-hint" multiple>
      <small class="thin-file-guidance" id="file-selected-hint">Choose files with the native picker. Your application must validate and receive the selected files.</small>
    </div>
  </div>
</section>

Disabled file picker

The native disabled picker is excluded from focus order and form submission.

Show code
<div class="thin-field" style="overflow-wrap: anywhere">
  <label for="file-disabled">Attachments</label>
  <div class="thin-file-input">
    <input id="file-disabled" name="attachments" type="file" aria-describedby="file-disabled-hint" disabled>
    <small class="thin-file-guidance" id="file-disabled-hint">Choose files with the native picker. Your application must validate and receive the selected files.</small>
  </div>
</div>

Application-authored drag presentation

A static snapshot of the documented data-dragging presentation hook. It is intentionally not an uploader or drop handler. Keep the native picker available when an application adds real drag handling.

Show code
<div class="thin-field" style="overflow-wrap: anywhere">
  <label for="file-drag">Attachments</label>
  <div class="thin-file-input" data-dragging>
    <input id="file-drag" name="attachments" type="file" aria-describedby="file-drag-hint" multiple>
    <small class="thin-file-guidance" id="file-drag-hint">Drag-state presentation preview only; choose files with the native picker. This example is not a drop target.</small>
  </div>
</div>
  • Empty — shown above
  • Files selected, including long filenames — shown above
  • Focused — shown above
  • Disabled — shown above
  • Application-authored drag state — shown above

Interaction and keyboard behavior

File selection, keyboard activation, filename display, form encoding, validation, and submission remain native. Thin-Sky does not turn this component into a drop target.

Accessibility

Associate the label and guidance. If an application adds drop behavior, keep the input operable and announce accepted files, errors, and drag-state changes in text.

Contract
NATIVE
Basis
Native <input type="range"> and <input type="file">; no APG widget
Evidence
  • tests/unit/library/form-inputs.test.ts

API

Wrap a native file input in .thin-file-input. Applications may set data-dragging only while a separately implemented drop target is active; it is a presentation hook, not uploader behavior.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

The native file picker remains keyboard accessible and submits selected files without CSS or JavaScript.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/file-input/style.ts

Composition

Derived from the examples and style specs, not authored.

Composes

Used by