StellarUI

<stellar-file-input>

Properties

Preview

Markup

Copy

<stellar-file-input
  label="Upload avatar"
  description="PNG, JPG, or WEBP up to 4MB."
  accept="image/png,image/jpeg,image/webp"
  name="avatar"
>
</stellar-file-input>

API

Complete props, events, slots, and implementation notes for the shipped file input.

Props

Prop	Type	Default
`tone`	`neutral \| primary \| secondary \| tertiary \| error`	`neutral`
`appearance`	`default \| ghost`	`default`
`size`	`xs \| sm \| md \| lg \| xl`	`md`
`label`	`string`	`''`
`description`	`string`	`''`
`error`	`string`	`''`
`accept`	`string`	`''`
`name`	`string`	`''`
`disabled`	`boolean`	`false`
`multiple`	`boolean`	`false`

Events

Event	Source	Notes
`change`	host	Redispatched from the inner native file input.

Slots

Slot	Notes
`label`	Optional content above the control. Overrides the `label` prop when present.
`description`	Optional helper content below the control. Overrides the `description` prop when present.
`error`	Optional validation message below the control. It replaces `description` while the inner control is invalid.

Notes

The public tag is `stellar-file-input`, backed by a real native `<input type="file">`.
The component stays thin: it forwards native file semantics like `accept`, `name`, `multiple`, and `files` instead of inventing a second upload API.
`required`, `aria-invalid`, and `custom-validity` forward to the inner native file input for validation-sensitive flows.
The host exposes `setCustomValidity()`, `checkValidity()`, `reportValidity()`, `validity`, `validationMessage`, and `willValidate`, so app code can use native-like validity APIs on the custom element.
For Datastar, prefer `data-attr:custom-validity="..."` on the custom element host instead of the Pro-only `data-custom-validity` attribute.
`label` and `description` match the rest of the StellarUI field-control family, so docs and forms stay aligned by default.
The visual baseline follows the shipped split field/button treatment through `::file-selector-button`.