If you need a prominent upload zone with a list of files, take CdsFileUpload; sending the files to the server is the job of CdsUploader.

Anatomy

The component is built on the same base as CdsTextInput: the label, the description, the messages, validation and the colors work the same way. What the field has of its own is the upload icon on the left (prepend-icon, upload by default), the names of the chosen files instead of the typed text and the file counter in the bottom block. Clearing (clearable) is on out of the box.

Storybook

Variations

Label and hints

label names the field, the requirements for the files go into description, and placeholder hints that a file can be dragged into the field. A chosen file is shown by its name.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref<File | null>(null);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Документ"
      description="Прикрепите один файл"
      placeholder="Выберите или перетащите файл в поле"
    />
  </div>
</template>

Several files

The multiple prop allows choosing several files at once — their names are listed separated by commas.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Можно выбрать несколько файлов"
      placeholder="Выберите или перетащите файлы в поле"
      multiple
    />
  </div>
</template>

Showing as tags

The chips prop shows every file as a separate tag (CdsTag) — a list of several files reads more easily.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Выбранные файлы показываются тегами"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      chips
    />
  </div>
</template>

Size and counter

show-size adds the size to the file name, counter shows the number and the total size under the field. Long names are truncated in the middle — the threshold is set by truncate-length (22 characters by default).

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="model"
      label="Вложения"
      description="Отображается размер файлов и счётчик"
      placeholder="Выберите или перетащите файл в поле"
      multiple
      show-size
      counter
    />
  </div>
</template>

Filter by type

filter-by-type accepts MIME types, wildcard types and extensions separated by commas (image/*,.pdf). The files that do not fit never get into the model — the rejected event reports them: show the user what exactly was rejected and why.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<File[]>([]);
const rejectedMessages = ref<string[]>([]);

// `rejected` срабатывает до обновления модели — флаг защищает свежие
// сообщения от сброса в обработчике update:model-value
let justRejected = false;

function onRejected(rejected: File[]) {
  rejectedMessages.value = rejected.map((file) => `${file.name} — не подходит по формату`);
  justRejected = true;
}

function onUpdate() {
  if (justRejected) {
    justRejected = false;

    return;
  }

  rejectedMessages.value = [];
}
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Сканы документов"
      description="Только изображения или PDF"
      placeholder="Выберите или перетащите файлы"
      filter-by-type="image/*,.pdf"
      multiple
      :error-messages="rejectedMessages"
      @rejected="onRejected"
      @update:model-value="onUpdate"
    />
  </div>
</template>

States

disabled blocks the field, readonly lets you look at the selection but not change it, loading shows an indicator — while the files are going to the server, for example.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { onMounted, ref } from 'vue';

const file = ref<File | null>(null);

// Файлы создаются только в браузере — SSR-сборка сайта обходится без File
onMounted(() => {
  file.value = new File([new Uint8Array(240_000)], 'отчёт-за-квартал.pdf', { type: 'application/pdf' });
});
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput label="Disabled" placeholder="Выберите файл" disabled />
    <CdsFileInput :model-value="file" label="Readonly" readonly />
    <CdsFileInput :model-value="file" label="Loading" loading />
  </div>
</template>

Slots

The zones of the field match CdsTextInput: prepend / append outside the border, prepend-inner / append-inner inside it. The extra selection slot replaces the standard list of file names.

Slot name	Description
label	Label content (replaces label)
description	Description content (replaces description)
prepend	Element before the field (replaces the upload icon)
append	Element after the field
prepend-inner	Element at the start of the field, inside the border
append-inner	Element at the end of the field, inside the border
selection	Your own display of the chosen files
clear	Your own clear icon (with clearable)
loader	Your own loading indicator (with loading)
counter	Counter content
details	The whole bottom block — messages and counter
messages	Content of the messages block

The selection slot receives the truncated file names (fileNames) and the total size (totalBytes, totalBytesReadable).

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput, CdsTag } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<File[]>([]);
</script>

<template>
  <div class="max-w-sm m-auto">
    <CdsFileInput
      v-model="files"
      label="Вложения"
      placeholder="Выберите или перетащите файлы"
      multiple
      show-size
      counter
    >
      <template #selection="{ fileNames }">
        <CdsTag v-for="name in fileNames" :key="name" prepend-icon="file" size="sm" :text="name" />
      </template>
    </CdsFileInput>
  </div>
</template>

Guidelines

Storybook

Scenarios

Submitting a form with attachments

The field takes part in CdsForm validation on a par with the others: rules receive the chosen files — check that the attachments are there and do not exceed the size limit before sending them to the server. chips and counter help the user keep track of the list.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsFileInput, CdsForm, CdsTextInput } from '@central-design-system/components';
import { ref } from 'vue';

const valid = ref(false);
const topic = ref('');
const files = ref<File[]>([]);
const loading = ref(false);
const sent = ref(false);

const topicRules = [(value: string) => !!value || 'Укажите тему обращения'];

const fileRules = [
  (value: File[]) => (value?.length ?? 0) > 0 || 'Приложите хотя бы один файл',
  (value: File[]) =>
    (value ?? []).every((file) => file.size <= 10 * 1024 * 1024) || 'Файл больше 10 МБ — сожмите его или разбейте архив'
];

async function submit() {
  if (!valid.value) return;

  try {
    loading.value = true;
    sent.value = false;
    await new Promise((resolve) => setTimeout(resolve, 1500));
    sent.value = true;
  } finally {
    loading.value = false;
  }
}
</script>

<template>
  <CdsForm v-model="valid" class="flex flex-col gap-2 w-[350px] m-auto" @submit.prevent="submit">
    <CdsTextInput v-model="topic" label="Тема обращения" :rules="topicRules" />

    <CdsFileInput
      v-model="files"
      label="Вложения"
      description="До 10 МБ каждый файл"
      placeholder="Выберите или перетащите файлы"
      :rules="fileRules"
      multiple
      chips
      counter
    />

    <CdsButton type="submit" :loading="loading" text="Отправить обращение" />

    <p v-if="sent" class="text-sm text-center">Обращение отправлено</p>
  </CdsForm>
</template>

An upload button without a field

The hide-input prop hides the field, leaving only the clickable icon — handy for embedding the upload into a toolbar or a comment line. Show the chosen files next to it yourself: here they are tags with closable, and a click on the cross removes a file from the model.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput, CdsTag } from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<File[]>([]);

function removeFile(name: string) {
  files.value = files.value.filter((file) => file.name !== name);
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <div class="flex items-center gap-1">
      <span>Прикрепите файлы к комментарию</span>
      <CdsFileInput v-model="files" hide-input hide-details multiple aria-label="Прикрепить файлы" />
    </div>

    <div v-if="files.length" class="flex flex-wrap justify-center gap-1">
      <CdsTag
        v-for="file in files"
        :key="file.name"
        prepend-icon="file"
        :text="file.name"
        closable
        @click:close="removeFile(file.name)"
      />
    </div>
  </div>
</template>

An image preview

filter-by-type="image/*" lets images through only, and the preview is built from the model value through URL.createObjectURL. Do not forget to release the previous URL — otherwise the chosen files pile up in the memory of the tab.

Sandbox Storybook

<script setup lang="ts">
import { CdsFileInput } from '@central-design-system/components';
import { onBeforeUnmount, ref, watch } from 'vue';

const file = ref<File | null>(null);
const previewUrl = ref('');

watch(file, (value) => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);

  previewUrl.value = value ? URL.createObjectURL(value) : '';
});

onBeforeUnmount(() => {
  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value);
});
</script>

<template>
  <div class="flex flex-col items-center gap-2 max-w-sm m-auto">
    <CdsFileInput
      v-model="file"
      class="w-full"
      label="Логотип компании"
      description="PNG, JPG или SVG"
      placeholder="Выберите или перетащите изображение"
      filter-by-type="image/*"
    />

    <img v-if="previewUrl" :src="previewUrl" alt="Превью логотипа" class="max-h-40 rounded" />
  </div>
</template>

API

Props

Name	Type	Default	Description
active	boolean | undefined	—	Active state of the field
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
appendInnerIcon	IconValue | undefined	—	Icon in the inner append slot, after the content of the field
baseColor	string | undefined	—	Color of the component in its inactive state
bgColor	string | undefined	—	Background color of the component
centerAffix	boolean | undefined	—	Vertically center the appendInner, prependInner, clearIcon and label elements.
chips	boolean | undefined	—	Show the chosen files as tags (CdsTag) instead of a list of names.
clearable	boolean | undefined	true	Shows the clear button
clearIcon	IconValue | undefined	'remove'	Icon of the clear button
color	string | undefined	—	Component color
counter	boolean | undefined	—	Show a counter of the number (and, with showSize, of the total size) of the chosen files.
counterSizeString	string | undefined	'$cds.fileInput.counterSize'	Localization key for the text of the counter with the file size.
counterString	string | undefined	'$cds.fileInput.counter'	Localization key for the text of the file count counter.
description	string | undefined	—	Description of the component, shown under the label
dirty	boolean | undefined	—	Marks that the value of the field was changed by the user
disabled	boolean | null | undefined	null	Disabled state
error	boolean | undefined	—	Error state
errorMessages	string | readonly string[] | null | undefined	[]	Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the rules prop. This field does not trigger validation.
filterByType	string | undefined	—	Filtering of files by MIME type or extension (image/*,.pdf, for example). The rejected files do not get into the model.
focused	boolean | undefined	—	Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior.
hideDetails	boolean | "auto" | undefined	—	Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
hideInput	boolean | undefined	—	Hide the field, leaving only the prepend icon (to use it as a button, for example).
hideMessages	boolean | undefined	—	Hide the messages under the input
hint	string | undefined	—	Hint text shown under the input
iconColor	string | boolean | undefined	—	Icon color. Accepts a boolean or a color string
id	string | undefined	—	Unique identifier of the component
label	string | undefined	—	Label text of the component
loading	string | boolean | undefined	—	Loading indicator for the component
maxErrors	string | number | undefined	1	Maximum number of validation errors shown
maxWidth	string | number | undefined	—	Maximum component width
messages	string | readonly string[] | undefined	[]	Messages shown under the input
minWidth	string | number | undefined	—	Minimum component width
modelValue	File | File[] | null | undefined	(props) => props.multiple ? [] : null	Value of the model: an array of files (with multiple), a single file or null.
multiple	boolean | undefined	—	Allow selecting several files.
name	string | undefined	—	Name of the input
persistentClearable	boolean | undefined	—	Always show the clear button, not only on hover or focus
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
placeholder	string | undefined	—	Placeholder text shown in an empty field (while no files are chosen yet).
prependIcon	IconValue | undefined	'upload'	Icon in the prepend slot, before the content
prependInnerIcon	IconValue | undefined	—	Icon in the inner prepend slot, before the content of the field
readonly	boolean | null | undefined	null	Read-only state
reverse	boolean | undefined	—	Reverses the order of the elements inside the field
rules	readonly ValidationRule[] | undefined	[]	Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string.
showSize	boolean | 1000 | 1024 | undefined	false	Show the size of the chosen files. A boolean or the base: 1000 (kB) or 1024 (KiB).
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
truncateLength	string | number | undefined	22	Maximum length of a file name before it is truncated (the characters at the start and at the end are kept).
validateOn	ValidateOn | undefined	—	Changes the type of the event that triggers validation
validationValue	any	—	Value used when applying the validation rules
width	string | number | undefined	—	Component width

Events

Name	Type	Description
click:control	[e: MouseEvent]	Fires on a click in the main area of the control.
mousedown:control	[e: MouseEvent]	Fires on a mouse button press in the main area of the control.
rejected	[files: File[]]	Fires when some of the files were rejected by the filterByType filter.
update:focused	[focused: boolean]	Fires when the element gains or loses focus.
update:modelValue	[value: File | File[]]	Fires when the list of the chosen files changes.

Slots

Name	Type	Description
append	CdsInputSlot	Adds an element after the input
append-inner	CdsInputDefaultSlot	Slot added at the end of the input
clear	CdsInputDefaultSlot & { props: Record<string, any>; }	Slot for a custom clear icon (shown when the clearable prop is true).
counter	CdsCounterSlot	Slot for a custom counter.
description	{ description: string | undefined; props: Record<string, any>; }	Default slot of the CdsDescription component
details	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
label	{ label: string | undefined; props: Record<string, any>; }	Default slot of the CdsLabel component
loader	LoaderSlotProps	Slot for a custom loader (shown when the loading prop is true).
message	CdsMessageSlot	Slot for customizing the content of a message
messages	CdsInputSlot	Slot for custom content that lets you customize how the messages are displayed
prepend	CdsInputSlot	Adds an element before the input
prepend-inner	CdsInputDefaultSlot	Slot added at the start of the input
selection	CdsFileInputSelectionSlot	Slot for a custom display of the chosen files.

Exposed

Name	Type	Description
controlRef	HTMLElement | undefined	Ref to the control of the input
fieldIconColor	string | undefined	Icon color
isDirty	boolean	Whether the input is dirty
isDisabled	boolean	Whether the input is disabled
isPure	boolean	Whether the input is pure
isReadonly	boolean	Whether the input is read-only
isValid	boolean | null	Whether the input is valid
isValidating	boolean	Whether the input is being validated
reset	() => Promise<void>	Resets the input to its initial state
resetValidation	() => Promise<void>	Resets the validation of the input
validate	(silent?: boolean) => Promise<string[]>	Validates the input