Component field guide

Explore live variants, compare states, and learn every prop. Pick a component to start.

LIVE COMPONENT

WelkAttachment

A native file picker with a selected-file list and small local image, video, and audio previews. Documents remain filename/size entries. Each selection replaces the previous batch. Invalid count, size, or type rejects the entire batch, clears the selection, and displays an error. Files are not uploaded automatically; object URLs are released when previews are removed.

Mission filesChoose one or more files. Up to 3 files. Maximum 5,242,880 bytes per file. Accepted: image/*,.pdf.

Usage

React / TSX

import { WelkAttachment } from "@welkui/react";

<WelkAttachment label="Mission files" maxFiles={3}
  maxFileSize={5242880} accept="image/*,.pdf"
  onFilesChange={(files) => console.log(files)} />

Import @welkui/react/styles.css once in your app. Stateful snippets belong inside a React component.

Variants and behavior

multiple=true: select a batch (default).
multiple=false: select one file.
Preview type is inferred from the file MIME type; unsupported media displays a preview error.

Visual variant gallery

These are real components, not screenshots. Compare their appearance and try the controls. Key props below each preview show what changes; use the usage example above for imports and component setup.

Multiple files

Choose a batch; local images, video, and audio receive previews. No files are uploaded.

Choose mission filesChoose one or more files.

Key propsmultiple

Single image

Only one image is allowed. Selecting a new image replaces the previous selection.

Choose a cover imageChoose one file. Accepted: image/*.

Key propsmultiple={false} accept="image/*"

Count, size and type limits

At most two images/PDFs, each up to 1 MiB. An invalid batch is cleared and an error explains why.

Choose up to two small filesChoose one or more files. Up to 2 files. Maximum 1,048,576 bytes per file. Accepted: image/*,.pdf.

Key propsmaxFiles={2} maxFileSize={1048576} accept="image/*,.pdf"

Disabled

The native file picker cannot be opened.

Attachments unavailableChoose one or more files.

Key propsdisabled

Usage notes and accessibility

Set both maxFiles and maxFileSize when resource limits matter. maxFileSize is per file, in bytes, not a total batch size. multiple=false always limits the picker to one file.
accept is a selection aid, not a security guarantee. Check file content, size, permissions and type again on the server before storing uploads.
Each accepted selection replaces the previous batch. onFilesChange receives the files; build your upload flow and progress reporting separately. Preview URLs are local and are revoked on cleanup.
Image, video and audio previews depend on browser codec support. PDFs and other documents are listed without embedded previews. Clear removes files; native form reset also clears the selection.

Props

Required props are marked in the default column. Other props are optional. ReactNode accepts text or JSX.

WelkAttachment prop reference
Prop	Type	Default	Description
`label`	`ReactNode`	Required	Visible, accessible control label.
`maxFiles`	`number`	Unlimited	Positive whole-number limit on the number of selected files.
`maxFileSize`	`number`	Unlimited	Positive maximum size per file in bytes; 5242880 equals 5 MiB.
`onFilesChange`	`(files: File[]) => void`	Unset	Receives accepted files, or [] after clearing/rejection.
`multiple`	`boolean`	true	Allows multiple file selection.
`accept`	`string`	Any file type	Comma-separated extensions or MIME types, such as image/*,.pdf.
`onChange`	`ChangeEventHandler<HTMLInputElement>`	Unset	Native picker change event.

Native props and refs

Inherits native input props except the fields replaced by this component's API: name, id, disabled, required, form, onBlur, onFocus, className, style, aria-* and data-* are supported. Forwards an input ref. type is fixed to file; value, defaultValue and children are not supported. Form reset clears files and previews without calling onFilesChange.

Project setup, styling and Next.js

Import @welkui/react/styles.css once in your app entry or Next.js root layout. The previews use the default theme; override --welk-* CSS tokens in your app to customize it.

For Next.js, put hooks and event handlers in a component beginning with "use client". Keep state local to the component using the control. The library preserves its client boundaries and uses your installed React version.

Use defaultValue or defaultChecked for uncontrolled fields, or a state value and its change callback for controlled fields. Do not switch between these modes during the lifetime of a field.

Modal and notification examples start closed: use their Try buttons to see them. Disabled examples are deliberately non-interactive. Validate forms, uploads, authentication, and server responses in your application; these components only provide UI.