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
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.
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.
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.
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.
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.
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.
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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
id | str | None | None | Sets exact native input identity or uses a generated ID. |
name | str | None | None | Sets the native form field name. |
accept | str | None | None | Sets the native picker hint without validating files. |
capture | "user" | "environment" | None (CFileInputCapture) | None | Sets the native media capture hint. |
multiple | bool | False | Allows more than one native selected file. |
required | bool | None | None | Sets native required validity outside Field. |
disabled | bool | None | None | Sets local disabledness outside Field; Form and fieldset still dominate. |
invalid | bool | None | None | Reflects 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) | None | Adds root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds 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(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Supplies the exact native input accessible name and visible primary text. |
id | str | None | None | Sets the nested native input identity. |
name | str | None | None | Sets the nested native form field name. |
accept | str | None | None | Sets the native picker hint without validating dropped files. |
capture | "user" | "environment" | None (CFileInputCapture) | None | Sets the native media capture hint. |
multiple | bool | False | Keeps all dropped or selected files instead of only the first. |
required | bool | None | None | Sets native required validity. |
disabled | bool | None | None | Disables browse and drop locally. |
invalid | bool | None | None | Reflects 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) | None | Adds label-root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds label-root inline styles. |
attrs | Mapping[str, object] | None | None | Adds trusted root label attributes. |
input_attrs | Mapping[str, object] | None | None | Adds 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 />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
accept | str | Uses the server value. | Reactively changes the native picker hint. |
capture | "user" | "environment" | Uses the server value. | Reactively changes the native capture hint. |
multiple | bool | Uses the server value. | Reactively changes single or multiple selection. |
required | bool | Uses the server or Field value. | Reactively changes native required validity outside Field. |
disabled | bool | Uses the server or Field value. | Reactively changes local disabledness outside Field. |
invalid | bool | Uses 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 />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
accept | str | Uses the server value. | Reactively changes the native picker hint. |
capture | "user" | "environment" | Uses the server value. | Reactively changes the native capture hint. |
multiple | bool | Uses the server value. | Reactively changes single or multiple selection and drop behavior. |
required | bool | Uses the server value. | Reactively changes native required validity. |
disabled | bool | Uses the server value. | Reactively changes local browse and drop disabledness. |
invalid | bool | Uses 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
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | no | {} (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.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-file-input-background | color | Picker or drop surface. | Canvas or the soft surface mix. |
--cui-file-input-foreground | color | Text color. | CanvasText |
--cui-file-input-border-color | color | Resting border. | a 38 percent CanvasText mix |
--cui-file-input-active-color | color | Focus and drag emphasis. | Highlight |
--cui-file-input-invalid-color | color | Invalid border. | scheme-aware red |
--cui-file-input-radius | length | Corner radius. | 0.65rem |
--cui-file-input-padding | padding | Drop surface padding. | size-dependent |
--cui-file-input-min-height | length | Minimum control height. | sm: 2.25rem; md: 2.75rem; lg: 3.25rem |
CDropTarget CSS variables
Apply these variables to CDropTarget or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-file-input-background | color | Drop surface. | Canvas or the soft surface mix. |
--cui-file-input-foreground | color | Text color. | CanvasText |
--cui-file-input-border-color | color | Resting border. | a 38 percent CanvasText mix |
--cui-file-input-active-color | color | Focus and drag emphasis. | Highlight |
--cui-file-input-invalid-color | color | Invalid border. | scheme-aware red |
--cui-file-input-radius | length | Corner radius. | 0.65rem |
--cui-file-input-padding | padding | Drop surface padding. | size-dependent |
--cui-file-input-min-height | length | Minimum 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
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-has-files | Styled root | present-or-absent | Present when the native FileList is nonempty. |
data-disabled | Styled root | present-or-absent | Mirrors effective native disabledness. |
data-required | Styled root | present-or-absent | Mirrors native required state. |
data-invalid | Styled root | present-or-absent | Mirrors external or native invalid state. |
data-variant | Styled root | outline | soft | plain | Mirrors effective variant. |
data-size | Styled root | sm | md | lg | Mirrors effective size. |
CDropTarget attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-has-files | Root label | present-or-absent | Present when the nested native FileList is nonempty. |
data-dragging | Root label | present-or-absent | Present during an accepted file drag over the target. |
data-disabled | Root label | present-or-absent | Mirrors effective native disabledness. |
data-required | Root label | present-or-absent | Mirrors native required state. |
data-invalid | Root label | present-or-absent | Mirrors external or native invalid state. |
data-variant | Root label | outline | soft | plain | Mirrors effective variant. |
data-size | Root label | sm | md | lg | Mirrors effective size. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CFileInput selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="file-input"] | FileInput native input | Stable picker root. |
CDropTarget selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="drop-target"] | DropTarget label | Stable drop surface and root attrs destination. |
[data-citry-ui-part="input"] | DropTarget native input | Stable native input destination. |
[data-citry-ui-part="label"] | DropTarget primary text | Stable visible label. |
[data-citry-ui-part="content"] | DropTarget supporting content | Stable supporting content. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] |
CFileInputCapture | Literal["user", "environment"] |
CFileInputVariant | Literal["outline", "soft", "plain"] |
CFileInputSize | Literal["sm", "md", "lg"] |
CDropTargetDefaultSlotData
Empty dataclass: {}.
Translation keys
-