FileInput

FileInput enables users to select files from their device's file system for upload or processing. It combines a text field displaying selected files with a customizable button that opens the system file browser. Use it for forms, media uploads, and document processing workflows.

Key features:

File type filtering: Restrict selection to specific file types using acceptsFileType
Multiple file selection: Enable users to select multiple files simultaneously
Directory selection: Allow folder selection instead of individual files
Customizable button: Configure button text, icons, position, and styling to match your design

Properties

`acceptsFileType`

An optional list of file types the input controls accepts provided as a string array.

<App>
  <FileInput acceptsFileType="{['.txt', '.jpg']}" />
</App>

Example: acceptsFileType

<App>
  <FileInput acceptsFileType="{['.txt', '.jpg']}" />
</App>

`autoFocus` (default: false)

If this property is set to true, the component gets the focus automatically when displayed.

`buttonIcon`

The ID of the icon to display in the button. You can change the default icon for all FileInput instances with the "icon.browse:FileInput" declaration in the app configuration file.

<App>
  <FileInput buttonIcon="drive" buttonLabel="Let there be drive" />
  <FileInput buttonIcon="drive" />
</App>

Example: buttonIcon

<App>
  <FileInput buttonIcon="drive" buttonLabel="Let there be drive" />
  <FileInput buttonIcon="drive" />
</App>

`buttonIconPosition` (default: "start")

This optional string determines the location of the button icon.

Available values: start (default), end

<App>
  <FileInput buttonIcon="drive" buttonLabel="End" buttonIconPosition="end" />
</App>

Example: buttonIconPosition

<App>
  <FileInput buttonIcon="drive" buttonLabel="End" buttonIconPosition="end" />
</App>

`buttonLabel`

This property is an optional string to set a label for the button part.

<App >
  <FileInput />
  <FileInput buttonLabel="I am the button label" />
</App>

Example: label

<App >
  <FileInput />
  <FileInput buttonLabel="I am the button label" />
</App>

`buttonPosition` (default: "end")

This property determines the position of the button relative to the input field.

Available values: start, end (default)

`buttonSize`

The size of the button (small, medium, large)

Available values:

Value	Description
`xs`	Extra small
`sm`	Small
`md`	Medium
`lg`	Large

<App>
  <FileInput buttonSize="lg" />
</App>

Example: buttonSize

<App>
  <FileInput buttonSize="lg" />
</App>

`buttonThemeColor` (default: "primary")

The button color scheme (primary, secondary, attention)

Available values: attention, primary (default), secondary

<App>
  <FileInput buttonThemeColor="secondary" />
</App>

Example: buttonThemeColor

<App>
  <FileInput buttonThemeColor="secondary" />
</App>

`buttonVariant`

The button variant to use

Available values: solid, outlined, ghost

<App>
  <FileInput buttonLabel="outlined" buttonVariant="outlined" />
</App>

Example: buttonVariant

<App>
  <FileInput buttonLabel="outlined" buttonVariant="outlined" />
</App>

`directory` (default: false)

This boolean property indicates whether the component allows selecting directories (true) or files only (false).

`enabled` (default: true)

This boolean property value indicates whether the component responds to user events (true) or not (false).

`initialValue`

This property sets the component's initial value.

`label`

This property sets the label of the component. If not set, the component will not display a label.

`labelBreak` (default: true)

This boolean value indicates whether the FileInput label can be split into multiple lines if it would overflow the available label width.

`labelPosition` (default: "top")

Places the label at the given position of the component.

Available values:

Value	Description
`start`	The left side of the input (left-to-right) or the right side of the input (right-to-left)
`end`	The right side of the input (left-to-right) or the left side of the input (right-to-left)
`top`	The top of the input (default)
`bottom`	The bottom of the input

`labelWidth`

This property sets the width of the FileInput component's label. If not defined, the label's width will be determined by its content and the available space.

`multiple` (default: false)

This boolean property enables to add not just one (false), but multiple files to the field (true). This is done either by dragging onto the field or by selecting multiple files in the browser menu after clicking the input field button.

<App>
  <FileInput multiple="false" />
  <FileInput multiple="true" />
</App>

Example: multiple

<App>
  <FileInput multiple="false" />
  <FileInput multiple="true" />
</App>

`placeholder`

An optional placeholder text that is visible in the input field when its empty.

`readOnly` (default: false)

Set this property to true to disallow changing the component value.

`required` (default: false)

Set this property to true to indicate it must have a value before submitting the containing form.

`validationStatus` (default: "none")

This property allows you to set the validation status of the input component.

Available values:

Value	Description
`valid`	Visual indicator for an input that is accepted
`warning`	Visual indicator for an input that produced a warning
`error`	Visual indicator for an input that produced an error

Events

`didChange`

This event is triggered when value of FileInput has changed.

Write in the input field and see how the Text underneath it is updated in accordingly.

<App var.field="">
  <FileInput onDidChange="(file) => field = file[0]?.name" />
  <Text value="{field}" />
</App>

Example: didChange

<App var.field="">
  <FileInput onDidChange="(file) => field = file[0]?.name" />
  <Text value="{field}" />
</App>

`gotFocus`

This event is triggered when the FileInput has received the focus.

Clicking on the FileInput in the example demo changes the label text. Note how clicking elsewhere resets the text to the original.

<App>
  <FileInput
    buttonLabel="{focused === true ? 'I got focused!' : 'I lost focus...'}"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
    var.focused="{false}"
  />
</App>

Example: gotFocus/lostFocus

<App>
  <FileInput
    buttonLabel="{focused === true ? 'I got focused!' : 'I lost focus...'}"
    onGotFocus="focused = true"
    onLostFocus="focused = false"
    var.focused="{false}"
  />
</App>

`lostFocus`

This event is triggered when the FileInput has lost the focus.

(See the example above)

Exposed Methods

`focus`

This API command focuses the input field of the component.

Signature: focus(): void

<App>
  <HStack>
    <Button label="Focus FileInput" onClick="fileInputComponent.focus()" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

Example: focus

<App>
  <HStack>
    <Button label="Focus FileInput" onClick="fileInputComponent.focus()" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

`open`

This API command triggers the file browsing dialog to open.

Signature: open(): void

<App>
  <HStack>
    <Button label="Open FileInput" onClick="fileInputComponent.open()" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

Example: open

<App>
  <HStack>
    <Button label="Open FileInput" onClick="fileInputComponent.open()" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

`setValue`

This method sets the current value of the component.

Signature: setValue(files: File[]): void

files: An array of File objects to set as the current value of the component.

(NOT IMPLEMENTED YET) You can use this method to set the component's current value programmatically.

`value`

This property holds the current value of the component, which is an array of files.

Signature: get value(): File[]

In the example below, select a file using the file browser of the FileInput component and note how the Text component displays the selected file's name:

<App>
  <HStack>
    <Text value="Selected file name: {fileInputComponent.value}" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

Example: value

<App>
  <HStack>
    <Text value="Selected file name: {fileInputComponent.value}" />
    <FileInput id="fileInputComponent" />
  </HStack>
</App>

Styling

The FileInput component does not theme variables directly. However, it uses the Button and TextBox components under the hood. Thus, modifying the styles of both of these components affects the FileInput.

See Button styling and TextBox styling.

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-FileInput--focus	none	none
borderColor-FileInput--focus	none	none
borderRadius-FileInput--focus	none	none
boxShadow-FileInput--focus	none	none
outlineColor-FileInput--focus	none	none
outlineOffset-FileInput--focus	none	none
outlineStyle-FileInput--focus	none	none
outlineWidth-FileInput--focus	none	none
textColor-FileInput--focus	none	none

FileInput

Properties

acceptsFileType

autoFocus (default: false)

buttonIcon

buttonIconPosition (default: "start")

buttonLabel

buttonPosition (default: "end")

buttonSize

buttonThemeColor (default: "primary")

buttonVariant

directory (default: false)

enabled (default: true)

initialValue

label

labelBreak (default: true)

labelPosition (default: "top")

labelWidth

multiple (default: false)

placeholder

readOnly (default: false)

required (default: false)

validationStatus (default: "none")

Events

didChange

gotFocus

lostFocus

Exposed Methods

focus

open

setValue

value

Styling

Theme Variables

`acceptsFileType`

`autoFocus` (default: false)

`buttonIcon`

`buttonIconPosition` (default: "start")

`buttonLabel`

`buttonPosition` (default: "end")

`buttonSize`

`buttonThemeColor` (default: "primary")

`buttonVariant`

`directory` (default: false)

`enabled` (default: true)

`initialValue`

`label`

`labelBreak` (default: true)

`labelPosition` (default: "top")

`labelWidth`

`multiple` (default: false)

`placeholder`

`readOnly` (default: false)

`required` (default: false)

`validationStatus` (default: "none")

`didChange`

`gotFocus`

`lostFocus`

`focus`

`open`

`setValue`

`value`