Theme
Version
GitHub PyPI Discord
On this page

File input and drop target

Use CFileInput when the native picker is the right control. Use CDropTarget when drag-and-drop should supplement the same click, touch, keyboard, FormData, reset, and required-validation behavior.

File selection at a glance

File selection at a glance
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class FileInputAtAGlance(Component):
    template = """
      <c-CStack gap="lg">
        <c-CField>
          <c-fill name="label">Profile photo</c-fill>
          <c-fill name="default"><c-CFileInput name="photo" accept="image/*" /></c-fill>
        </c-CField>
        <c-CDropTarget label="Project files" name="project_files" multiple>
          Drop files here or browse from this device
        </c-CDropTarget>
      </c-CStack>
    """


preview = FileInputAtAGlance()

preview  # noqa: B018

Use FileInput in Field

Field supplies the visible label, description, error relationship, required state, and disabled state. File inputs do not support readonly.

FileInput in Field
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class FileInputField(Component):
    template = """
      <c-CField required>
        <c-fill name="label">Supporting document</c-fill>
        <c-fill name="default">
          <c-CFileInput name="document" accept="application/pdf" />
        </c-fill>
        <c-fill name="description">Choose one PDF for review.</c-fill>
        <c-fill name="error">Choose a supporting document.</c-fill>
      </c-CField>
    """


preview = FileInputField()

preview  # noqa: B018
<c-CField required>
  <c-fill name="label">Supporting document</c-fill>
  <c-fill name="default">
    <c-CFileInput name="document" accept="application/pdf" />
  </c-fill>
</c-CField>

Add a drop target

DropTarget always keeps its native file input. Dragging is an enhancement; click, touch, and keyboard users open the system picker through the same control. Its label is the exact accessible name, while default content adds visible instructions.

Drop files or browse
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class FileDropTarget(Component):
    template = """
      <div x-data="{names: []}">
        <c-CDropTarget
          label="Supporting documents"
          name="documents"
          multiple
          @change="names = [...$event.target.files].map(file => file.name)"
        >
          PDF or image files
        </c-CDropTarget>
        <p x-text="names.join(', ')"></p>
      </div>
    """


preview = FileDropTarget()

preview  # noqa: B018

Read files from native events. On DropTarget the event bubbles to the label, so use event.target.files, not currentTarget.files.

<c-CDropTarget
  label="Supporting documents"
  name="documents"
  multiple
  @change="files = [...$event.target.files]"
>
  PDF or image files
</c-CDropTarget>

Select several files

multiple uses native FileList ordering and repeated multipart form values. The component does not deduplicate, render, remove, or upload files.

Select several files
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class MultipleFiles(Component):
    template = """
      <form @submit.prevent="window.__selectedFiles = [...new FormData($event.target).getAll('evidence')]">
        <c-CDropTarget label="Research evidence" name="evidence" multiple variant="soft">
          Select or drop several files
        </c-CDropTarget>
        <c-CButton type="submit">Inspect FormData</c-CButton>
      </form>
    """


preview = MultipleFiles()

preview  # noqa: B018

Configure picker hints

accept and capture are native picker hints. They are not validation or a security boundary, and capture support differs by device and browser.

Picker hints
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class FileCaptureHints(Component):
    template = """
      <c-CGroup>
        <c-CField>
          <c-fill name="label">Take a photo</c-fill>
          <c-fill name="default">
            <c-CFileInput name="photo" accept="image/*" capture="environment" />
          </c-fill>
        </c-CField>
        <c-CField>
          <c-fill name="label">Record a note</c-fill>
          <c-fill name="default">
            <c-CFileInput name="note" accept="audio/*" capture="user" />
          </c-fill>
        </c-CField>
      </c-CGroup>
    """


preview = FileCaptureHints()

preview  # noqa: B018

Respect disabled ownership

Local disabled state, enclosing CForm state, and native disabled fieldsets prevent browse and drop. Native form reset clears the current FileList.

Disabled file controls
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class DisabledFiles(Component):
    template = """
      <c-CStack>
        <c-CFileInput c-attrs="{'aria-label': 'Disabled picker'}" disabled />
        <fieldset disabled>
          <legend>Archived upload</legend>
          <c-CDropTarget label="Archived evidence" c-disabled="False">
            Uploads are unavailable
          </c-CDropTarget>
        </fieldset>
      </c-CStack>
    """


preview = DisabledFiles()

preview  # noqa: B018

Customize surfaces

Variants, sizes, public variables, and parts customize the picker and drop surface. The operating-system picker itself is outside the page styling contract.

Customize file controls
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class CustomizedFiles(Component):
    css = """
      :where(.evidence-drop) {
        --cui-file-input-background: light-dark(#eef8f2, #10271d);
        --cui-file-input-border-color: light-dark(#28724d, #6ed59b);
        --cui-file-input-active-color: light-dark(#15623e, #82e8ad);
        --cui-file-input-radius: 1.25rem;
      }
    """
    template = """
      <c-CDropTarget label="Botanical records" class_="evidence-drop" size="lg">
        CSV, PDF, or field images
      </c-CDropTarget>
    """


preview = CustomizedFiles()

preview  # noqa: B018

Validate and upload in the application

Never trust the file name, MIME type, extension, path, or accept match. Validate again on the server. Build previews with application-owned object URLs and revoke them when no longer needed. Compose upload progress with CProgress; this family does not own upload transport, retry, or cancellation.

API reference

Inputs

CFileInput server inputs

Server inputs are passed in a template through <c-CFileInput ... /> or in Python through CFileInput(...).

InputTypeDefaultEffect
idstr | NoneNoneSets exact native input identity or uses a generated ID.
namestr | NoneNoneSets the native form field name.
acceptstr | NoneNoneSets the native picker hint without validating files.
capture"user" | "environment" | None (CFileInputCapture)NoneSets the native media capture hint.
multipleboolFalseAllows more than one native selected file.
requiredbool | NoneNoneSets native required validity outside Field.
disabledbool | NoneNoneSets local disabledness outside Field; Form and fieldset still dominate.
invalidbool | NoneNoneReflects an external invalid state outside Field.
variant"outline" | "soft" | "plain" (CFileInputVariant)"outline"Selects the picker surface.
size"sm" | "md" | "lg" (CFileInputSize)"md"Selects picker geometry.
class_CClassValue | None (CClassValue)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted native attributes without replacing owned file input semantics or state.

CDropTarget server inputs

Server inputs are passed in a template through <c-CDropTarget ... /> or in Python through CDropTarget(...).

InputTypeDefaultEffect
labelstrrequiredSupplies the exact native input accessible name and visible primary text.
idstr | NoneNoneSets the nested native input identity.
namestr | NoneNoneSets the nested native form field name.
acceptstr | NoneNoneSets the native picker hint without validating dropped files.
capture"user" | "environment" | None (CFileInputCapture)NoneSets the native media capture hint.
multipleboolFalseKeeps all dropped or selected files instead of only the first.
requiredbool | NoneNoneSets native required validity.
disabledbool | NoneNoneDisables browse and drop locally.
invalidbool | NoneNoneReflects external invalid state.
variant"outline" | "soft" | "plain" (CFileInputVariant)"outline"Selects drop surface treatment.
size"sm" | "md" | "lg" (CFileInputSize)"md"Selects drop surface geometry.
class_CClassValue | None (CClassValue)NoneAdds label-root classes.
styleCStyleValue | None (CStyleValue)NoneAdds label-root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted root label attributes.
input_attrsMapping[str, object] | NoneNoneAdds unrelated trusted attributes to the nested native input.

CFileInput client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CFileInput />.

InputTypeOmitted behaviorEffect
acceptstrUses the server value.Reactively changes the native picker hint.
capture"user" | "environment"Uses the server value.Reactively changes the native capture hint.
multipleboolUses the server value.Reactively changes single or multiple selection.
requiredboolUses the server or Field value.Reactively changes native required validity outside Field.
disabledboolUses the server or Field value.Reactively changes local disabledness outside Field.
invalidboolUses the server or Field value.Reactively reflects external invalidity outside Field.
variant"outline" | "soft" | "plain"Uses the server value.Reactively changes surface treatment.
size"sm" | "md" | "lg"Uses the server value.Reactively changes geometry.

CDropTarget client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CDropTarget />.

InputTypeOmitted behaviorEffect
acceptstrUses the server value.Reactively changes the native picker hint.
capture"user" | "environment"Uses the server value.Reactively changes the native capture hint.
multipleboolUses the server value.Reactively changes single or multiple selection and drop behavior.
requiredboolUses the server value.Reactively changes native required validity.
disabledboolUses the server value.Reactively changes local browse and drop disabledness.
invalidboolUses the server value.Reactively reflects external invalidity.
variant"outline" | "soft" | "plain"Uses the server value.Reactively changes surface treatment.
size"sm" | "md" | "lg"Uses the server value.Reactively changes geometry.

Slots

Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.

CDropTarget slots

SlotRequiredDataFallback
defaultno{} (CDropTargetDefaultSlotData)No supporting text. Content must be noninteractive phrasing content.

Events

-

Methods

-

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CFileInput CSS variables

Apply these variables to CFileInput or one of its ancestors.

VariableTypePurposeDefault
--cui-file-input-backgroundcolorPicker or drop surface.Canvas or the soft surface mix.
--cui-file-input-foregroundcolorText color.CanvasText
--cui-file-input-border-colorcolorResting border.a 38 percent CanvasText mix
--cui-file-input-active-colorcolorFocus and drag emphasis.Highlight
--cui-file-input-invalid-colorcolorInvalid border.scheme-aware red
--cui-file-input-radiuslengthCorner radius.0.65rem
--cui-file-input-paddingpaddingDrop surface padding.size-dependent
--cui-file-input-min-heightlengthMinimum control height.sm: 2.25rem; md: 2.75rem; lg: 3.25rem

CDropTarget CSS variables

Apply these variables to CDropTarget or one of its ancestors.

VariableTypePurposeDefault
--cui-file-input-backgroundcolorDrop surface.Canvas or the soft surface mix.
--cui-file-input-foregroundcolorText color.CanvasText
--cui-file-input-border-colorcolorResting border.a 38 percent CanvasText mix
--cui-file-input-active-colorcolorFocus and drag emphasis.Highlight
--cui-file-input-invalid-colorcolorInvalid border.scheme-aware red
--cui-file-input-radiuslengthCorner radius.0.65rem
--cui-file-input-paddingpaddingDrop surface padding.size-dependent
--cui-file-input-min-heightlengthMinimum drop surface height input.sm: 2.25rem; md: 2.75rem; lg: 3.25rem

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CFileInput attributes

AttributeElementTypeMeaning
data-has-filesStyled rootpresent-or-absentPresent when the native FileList is nonempty.
data-disabledStyled rootpresent-or-absentMirrors effective native disabledness.
data-requiredStyled rootpresent-or-absentMirrors native required state.
data-invalidStyled rootpresent-or-absentMirrors external or native invalid state.
data-variantStyled rootoutline | soft | plainMirrors effective variant.
data-sizeStyled rootsm | md | lgMirrors effective size.

CDropTarget attributes

AttributeElementTypeMeaning
data-has-filesRoot labelpresent-or-absentPresent when the nested native FileList is nonempty.
data-draggingRoot labelpresent-or-absentPresent during an accepted file drag over the target.
data-disabledRoot labelpresent-or-absentMirrors effective native disabledness.
data-requiredRoot labelpresent-or-absentMirrors native required state.
data-invalidRoot labelpresent-or-absentMirrors external or native invalid state.
data-variantRoot labeloutline | soft | plainMirrors effective variant.
data-sizeRoot labelsm | md | lgMirrors effective size.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CFileInput selectors

SelectorElementPurpose
[data-citry-ui-part="file-input"]FileInput native inputStable picker root.

CDropTarget selectors

SelectorElementPurpose
[data-citry-ui-part="drop-target"]DropTarget labelStable drop surface and root attrs destination.
[data-citry-ui-part="input"]DropTarget native inputStable native input destination.
[data-citry-ui-part="label"]DropTarget primary textStable visible label.
[data-citry-ui-part="content"]DropTarget supporting contentStable supporting content.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue]
CFileInputCaptureLiteral["user", "environment"]
CFileInputVariantLiteral["outline", "soft", "plain"]
CFileInputSizeLiteral["sm", "md", "lg"]

CDropTargetDefaultSlotData

Empty dataclass: {}.

Translation keys

-