The uploader sends the files over HTTP itself. If the files only have to be picked and sent together with the form, take the CdsFileInput field, and for a drop zone with image previews — CdsFileUpload.

Anatomy

The first diagram is the frame: the label, the description, the upload button and the messages. The second one is an item of the file list during the upload: the status, the name as a link, the actions and the progress bar.

Storybook

Variations

The upload button

By default the upload is started by the primary "Загрузить файл" button with the upload-icon icon. The button-props prop passes any CdsButton props to the button, and the default slot replaces it entirely — the ready props of the button arrive in the props slot argument.

Sandbox Storybook

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

const documents = ref<NUploader.IUploadFile[]>([]);
const photos = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="documents"
      label="Свойства кнопки"
      action="https://user1694090019726.requestly.dev/upload"
      :button-props="{ variant: 'soft', text: 'Прикрепить файлы' }"
    />

    <CdsUploader
      v-model="photos"
      label="Своя кнопка через слот"
      action="https://user1694090019726.requestly.dev/upload"
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" variant="soft" color="neutral" prepend-icon="add" text="Добавить фото" />
      </template>
    </CdsUploader>
  </div>
</template>

Allowed file types

The accept prop limits the choice in the system dialog and filters out the unsuitable files on a drop — the rejected ones arrive in the reject event.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файла"
      description="Подойдут только изображения jpeg, jpg или png"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
    />
  </div>
</template>

The file list

The list of the uploaded files lives in v-model — put the files received from the server into it and they will be shown right away. The show-upload-list prop controls the list: false hides it entirely, an object turns on the download and removal icons.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  },
  {
    uid: '2',
    name: 'B2b-elbcp-180x130.png',
    status: 'done',
    url: 'https://upload.wikimedia.org/wikipedia/commons/a/ae/B2b-elbcp-180x130.png'
  }
]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Документы"
      description="Уже загруженные файлы приходят через v-model"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
    />
  </div>
</template>

Number of files

The max-count prop limits the length of the list: with max-count="1" a new file replaces the previous one, with a larger limit the extra files are dropped.

Sandbox Storybook

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

const avatar = ref<NUploader.IUploadFile[]>([]);
const documents = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader
      v-model="avatar"
      label="Фото профиля"
      description="Новый файл заменяет предыдущий"
      action="https://user1694090019726.requestly.dev/upload"
      accept="image/png, image/jpeg"
      :max-count="1"
    />

    <CdsUploader
      v-model="documents"
      label="Документы"
      description="Не больше трёх файлов — лишние отбрасываются"
      action="https://user1694090019726.requestly.dev/upload"
      :max-count="3"
    />
  </div>
</template>

Uploading directories

The directory prop turns on picking a whole folder — the files are collected from it recursively, on a drop as well.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([]);
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка директории"
      description="Выберите папку — файлы соберутся из неё рекурсивно"
      action="https://user1694090019726.requestly.dev/upload"
      directory
    >
      <template #default="{ props }">
        <CdsButton v-bind="props" text="Загрузить директорию" />
      </template>
    </CdsUploader>
  </div>
</template>

States

disabled blocks the button and removes the removal icons from the list, readonly forbids changing the list but keeps the downloading.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsUploader } from '@central-design-system/components';

const files: NUploader.IUploadFile[] = [
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
];
</script>

<template>
  <div class="flex flex-col gap-2 w-[350px] m-auto">
    <CdsUploader label="Disabled" description="Загрузка недоступна" disabled />

    <CdsUploader
      label="Readonly"
      description="Список нельзя изменить, скачивание работает"
      :model-value="files"
      :show-upload-list="{ showDownloadIcon: true }"
      readonly
    />
  </div>
</template>

Slots

When props are not enough, the content of any block is replaced by a slot.

Slot name	Description
label	Label content (replaces label)
description	Description content (replaces description)
prepend	Element before the upload button
default	Your own upload button; receives the ready props for CdsButton
append	Element after the upload button
messages	Content of the messages block
itemRender	Your own rendering of a list item; receives file, fileList and actions

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import {
  CdsButton,
  CdsFunctionalButton,
  CdsIcon,
  CdsListItem,
  CdsTooltip,
  CdsUploader
} from '@central-design-system/components';
import { ref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([
  {
    uid: '1',
    name: 'dummy.pdf',
    status: 'done',
    url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf'
  }
]);

const clearAll = () => {
  files.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader v-model="files" action="https://user1694090019726.requestly.dev/upload">
      <template #label>
        <span class="flex items-center gap-0.5">
          Загрузка файла
          <CdsTooltip text="Дополнительная информация">
            <template #activator="{ props }">
              <CdsIcon name="info" v-bind="props" />
            </template>
          </CdsTooltip>
        </span>
      </template>

      <template #description> Подойдёт любой формат — <strong>jpg, png, doc, zip</strong> — до 10 МБ. </template>

      <template #default="{ props }">
        <CdsButton v-bind="props" text="Выбрать файл" />
      </template>

      <template #append>
        <CdsFunctionalButton icon="delete" aria-label="Удалить все файлы" @click="clearAll">
          <CdsTooltip activator="parent">Удалить все файлы</CdsTooltip>
        </CdsFunctionalButton>
      </template>

      <template #messages>Файлы проверяются после загрузки</template>

      <template #itemRender="{ file, actions }">
        <CdsListItem :title="file?.name">
          <template #append>
            <CdsFunctionalButton icon="download" aria-label="Скачать файл" @click="actions.download" />
            <CdsFunctionalButton icon="delete" aria-label="Удалить файл" @click="actions.remove" />
          </template>
        </CdsListItem>
      </template>
    </CdsUploader>
  </div>
</template>

Guidelines

Storybook

Scenarios

Deferred sending

The before-upload hook returning false turns the automatic sending off: the files pile up in the list, and the upload is started by a separate button in the append slot — together with the submission of the whole form, for example.

Sandbox Storybook

<script setup lang="ts">
import type { NUploader } from '@central-design-system/components';
import { CdsButton, CdsToast, CdsUploader } from '@central-design-system/components';
import { ref, unref } from 'vue';

const files = ref<NUploader.IUploadFile[]>([]);
const loading = ref(false);
const uploaded = ref(false);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  files.value = [...(unref(files) || []), file];
  return false;
};

const handleUpload = async () => {
  loading.value = true;
  await new Promise((resolve) => setTimeout(resolve, 3000));
  files.value = [];
  loading.value = false;
  uploaded.value = true;
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Выберите файлы"
      description="Файлы копятся в списке, загрузку запускает кнопка"
      :before-upload="beforeUpload"
      :show-upload-list="{ showRemoveIcon: true }"
    >
      <template #default="{ props }">
        <CdsButton
          variant="soft"
          color="brand"
          text="Выбрать файлы"
          :disabled="props.disabled"
          :readonly="props.readonly"
        />
      </template>
      <template #append>
        <CdsButton prepend-icon="upload" :loading="loading" :disabled="!files.length" @click="handleUpload">
          Загрузить файлы
        </CdsButton>
      </template>
    </CdsUploader>
    <CdsToast v-model="uploaded" title="Файлы успешно загружены" status="success" />
  </div>
</template>

A check before the upload

The same before-upload is the place for validation: return false and the file will not go to the server. A rejected file still gets into the list — remove it in the change handler and show the reason through error-messages.

Sandbox Storybook

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

const MAX_SIZE_MB = 5;

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const beforeUpload = (file: NUploader.IUploadFile): boolean => {
  const valid = (file.size ?? 0) <= MAX_SIZE_MB * 1024 * 1024;

  if (!valid) {
    errors.value = [`«${file.name}» больше ${MAX_SIZE_MB} МБ`];
  }

  return valid;
};

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  if (info instanceof Event) return;

  files.value = info.fileList.filter((file) => file.status);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Вложения"
      :description="`Любые файлы до ${MAX_SIZE_MB} МБ`"
      action="https://user1694090019726.requestly.dev/upload"
      :error-messages="errors"
      :before-upload="beforeUpload"
      @change="handleChange"
    />
  </div>
</template>

Upload errors

A file rejected by the server stays in the list with the error status. The show-tooltip-with-error prop shows the server response in a tooltip next to the status, and the error event lets you collect the messages under the field — here they pile up in error-messages and are reset when the file is removed.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([]);
const errors = ref<string[]>([]);

const handleError = (
  _error: NUploader.IUploadRequestError | ProgressEvent,
  response: { message?: string } | null,
  file: NUploader.IUploadFile
) => {
  errors.value = [...errors.value, `${response?.message ?? 'Ошибка сервера'}: ${file.name}`];
};

const handleRemove = () => {
  errors.value = [];
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка с ошибкой"
      description="Тестовый сервер отклоняет любой файл"
      action="https://user1694090019726.requestly.dev/upload-error"
      :error-messages="errors"
      show-tooltip-with-error
      @error="handleError"
      @remove="handleRemove"
    />
  </div>
</template>

Uploading without a server

The custom-request prop replaces the built-in XHR transport with your own function: it receives the file and the onProgress, onSuccess, onError callbacks and returns an object with an abort method. Here the upload is simulated with a timer — files can be sent through an SDK or a WebSocket in the same way.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([]);

// Имитация загрузки: прогресс по таймеру вместо XHR-запроса
const customRequest = ({ onProgress, onSuccess }: NUploader.IUploadRequestOption) => {
  let percent = 0;

  const timer = setInterval(() => {
    percent += 20;
    onProgress?.({ percent });

    if (percent >= 100) {
      clearInterval(timer);
      onSuccess?.({});
    }
  }, 400);

  return { abort: () => clearInterval(timer) };
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка без сервера"
      description="Файл никуда не отправляется — прогресс имитируется"
      :custom-request="customRequest"
      :show-upload-list="{ showRemoveIcon: true }"
    />
  </div>
</template>

Events

The component reports every step: change — any change of the list, progress, success and error — the course of the upload, remove, drop, reject, download, preview — the actions of the user. Open the console to see them.

Sandbox Storybook

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

const files = ref<NUploader.IUploadFile[]>([]);

const handleChange = (info: NUploader.IUploadChangeParam<NUploader.IUploadFile> | Event) => {
  console.log('onChange', info);
};
const handleProgress = (event: NUploader.IUploadChangeParam['event'], file: NUploader.IUploadFile) => {
  console.log('onProgress', event, file);
};
const handleSuccess = (response: Record<string, any>, file: NUploader.IUploadFile) => {
  console.log('onSuccess', response, file);
};
const handleError = (
  event: NUploader.IUploadRequestError | ProgressEvent,
  response: any,
  file: NUploader.IUploadFile
) => {
  console.log('onError', event, response, file);
};
const handleRemove = (file: NUploader.IUploadFile) => {
  console.log('onRemove', file);
};
const handleDrop = (event: DragEvent) => {
  console.log('onDrop', event);
};
const handleReject = (rejected: NUploader.IUploadFile[]) => {
  console.log('onReject', rejected);
};
const handleDownload = (file: NUploader.IUploadFile) => {
  console.log('onDownload', file);
};
const handlePreview = (file: NUploader.IUploadFile) => {
  console.log('onPreview', file);
};
</script>

<template>
  <div class="w-[350px] m-auto">
    <CdsUploader
      v-model="files"
      label="Загрузка файлов"
      description="Откройте консоль, чтобы увидеть все циклы событий"
      action="https://user1694090019726.requestly.dev/upload"
      :show-upload-list="{ showDownloadIcon: true, showRemoveIcon: true }"
      @change="handleChange"
      @progress="handleProgress"
      @success="handleSuccess"
      @error="handleError"
      @remove="handleRemove"
      @drop="handleDrop"
      @reject="handleReject"
      @download="handleDownload"
      @preview="handlePreview"
    />
  </div>
</template>

API

Props

Name	Type	Default	Description
accept	string | string[] | undefined	''	Allowed file types
action	NUploader.TAction | undefined	''	URL the files are uploaded to
activeColor	string | undefined	—	Color of the component in its active state
appendIcon	IconValue | undefined	—	Icon in the append slot, after the content
baseColor	string | undefined	—	Color of the component in its inactive state
beforeUpload	((file: NUploader.IUploadFile<any>, fileList: NUploader.IUploadFile<any>[]) => NUploader.TBeforeUploadFileType | Promise<void | NUploader.TBeforeUploadFileType>) | undefined	—	Lifecycle hook called before a file is uploaded
bgColor	string | undefined	—	Background color of the component
buttonProps	Partial<CdsButtonProps> | undefined	null	Props for the CdsButton component
capture	boolean | "user" | "environment" | undefined	—	Type of the media the file is captured from on mobile devices
centerAffix	boolean | undefined	true	Vertically center the appendInner, prependInner, clearIcon and label elements.
color	string | undefined	—	Component color
customRequest	((options: NUploader.IUploadRequestOption<any>) => void) | undefined	—	Your own file upload request. Overrides the default xhr
data	Record<string, unknown> | ((file: string | Blob | NUploader.IRcFile) => Record<string, unknown>) | {} | undefined	{}	Parameters of the file upload or a function returning them
defaultFileList	NUploader.IUploadFile<any>[] | undefined	—	Default list of files
description	string | undefined	—	Description of the component, shown under the label
direction	"horizontal" | "vertical" | undefined	'horizontal'	Switches the component between horizontal and vertical layout.
directory	boolean | undefined	—	Upload directories
disabled	boolean | null | undefined	null	Disabled state
downloadIcon	IconValue | undefined	'download'	File download icon
error	boolean | undefined	—	Puts the component into the 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.
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.
headers	NUploader.TUploadRequestHeaders | undefined	—	Request headers
hideDetails	boolean | "auto" | undefined	—	Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
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
isImageUrl	((file: NUploader.IUploadFile<any>) => boolean) | undefined	—	Configuration of the thumbnails of the uploaded files (not supported yet)
itemRender	NUploader.TItemRender<any> | undefined	—	Render function for an item of the uploaded file list
label	string | undefined	—	Label text of the component
listType	NUploader.TUploadListType | undefined	'text'	Type of the uploaded file list ('text' only is supported)
maxCount	number | undefined	—	Maximum number of uploaded files
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
method	NUploader.TUploadRequestMethod | undefined	—	HTTP method of the upload request
minWidth	string | number | undefined	—	Minimum component width
modelValue	any	—	Value of the component in v-model. If the component supports the multiple prop, an empty array is used by default.
multiple	boolean | undefined	true	Uploading several files at once
name	string | undefined	—	Name of the input
openFileDialogOnClick	boolean | undefined	—	Whether to open the system dialog on a click on the uploader
persistentHint	boolean | undefined	—	Always show the hint, not only on focus
prependIcon	IconValue | undefined	—	Icon in the prepend slot, before the content
readonly	boolean | null | undefined	null	Read-only state
removeIcon	IconValue | undefined	'delete'	File removal icon
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.
showTooltipWithError	boolean | undefined	false	Whether to show a tooltip with the error next to every file
showUploadList	boolean | NUploader.TShowUploadList | undefined	true	Show the list of the uploaded files
size	number | "xs" | "sm" | "md" | "lg" | "xl" | undefined	'md'	Size of the component
tag	string | JSXComponent<any> | undefined	'span'	Custom HTML tag or component to render
textColor	string | undefined	—	Text color of the component
theme	string | undefined	—	Component theme
uploadIcon	IconValue | undefined	'upload'	File upload icon
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
withCredentials	boolean | undefined	—	Send the request with cookies

Events

Name	Type	Description
change	[info: NUploader.IUploadChangeParam<NUploader.IUploadFile<any>>]	Fires when the field changes
download	[file: NUploader.IUploadFile<any>]	Fires when a file is downloaded
drop	[event: DragEvent]	Fires when a file is dropped
error	[error: ProgressEvent<EventTarget> | NUploader.IUploadRequestError, response: any, file: NUploader.IUploadFile<any>]	Fires when a file upload fails
preview	[file: NUploader.IUploadFile<any>]	Fires when a file preview is opened
progress	[event: { percent: number; } | undefined, file: NUploader.IUploadFile<any>]	Fires while a file is being uploaded
reject	[fileList: NUploader.IUploadFile<any>[]]	Fires when a file upload is rejected
remove	[file: NUploader.IUploadFile<any>]	Fires when a file is removed
success	[response: Record<string, unknown>, file: NUploader.IUploadFile<any>]	Fires when a file has been uploaded successfully
update:modelValue	[fileList: NUploader.IUploadFile<any>[]]	Fires when the value changes (v-model)

Slots

Name	Type	Description
append	any	Content of the append slot after the upload button.
default	{ props: Partial<CdsButtonProps>; }	The upload button or activator. Receives the props for CdsButton.
description	any	Description under the label.
itemRender	{ originNode: VNode<RendererNode, RendererElement, { [key: string]: any; }>; file?: NUploader.IUploadFile<any> | undefined; fileList?: NUploader.IUploadFile<any>[] | undefined; actions: { download?: (() => void) | undefined; preview?: (() => void) | undefined; remove?: (() => void) | undefined; }; }	Custom rendering of an item of the uploaded file list.
label	any	Label of the upload field.
messages	any	Hint and error messages.
prepend	any	Content of the prepend slot before the upload button.

Exposed

Name	Type	Description
fileList	NUploader.IUploadFile<any>[]	Current list of files together with their upload statuses.
uploadRef	NUploader.IUploaderRef | undefined	Ref to the inner upload element — gives access to choosing files programmatically and to aborting.