FilesCard 📇

Introduction

The FilesCard component is a flexible file display component that supports visual presentation of various file types (images, documents, compressed files, etc.), including file icons, names, descriptions, status and other information. It provides rich customization options and interactive features, suitable for file management, upload preview and other scenarios.

Code Examples

Basic Usage

Set name property, and name has no suffix. name="Test File"

Test File

Unknown

Set name property, has file suffix. name="Test File.pdf"

Test File

.pdf

Pdf

Supports matching built-in icons based on name suffix

Test doc suffix

.doc

Word

Test xls suffix

.xls

Excel

Test ppt suffix

.ppt

Ppt

Test txt suffix

.txt

Txt

Test pdf suffix

.pdf

Pdf

Test png suffix

.png

Image

Test jpg suffix

.jpg

Image

Test gif suffix

.gif

Image

Test mp4 suffix

.mp4

Video

Test mp3 suffix

.mp3

Audio

Test zip suffix

.zip

Zip

Test rar suffix

.rar

Zip

Test 7z suffix

.7z

Zip

Test lnk suffix

.lnk

Link

Test obj suffix

.obj

3D

Test fbx suffix

.fbx

3D

Test glb suffix

.glb

3D

Test sql suffix

.sql

Database

Test db suffix

.db

Database

Test md suffix

.md

Markdown

Test js suffix

.js

Code

Test py suffix

.py

Code

Test java suffix

.java

Code

Test php suffix

.php

Code

Test json suffix

.json

Code

If there is a suffix but can't match common icons, it defaults to File

https://dd.comMultiple special characters.suffix

.self

File

Basic Usage

You can get the colorMap built-in file type fileType: color object on the component instance. Built-in 16 file type icons.

<script setup lang="ts">
import type { FilesType } from 'vue-element-plus-x/types/FilesCard';

const filesCardRef = ref();
const colorMap = ref({}) as Ref<Record<FilesType, string>>;

onMounted(() => {
  // Get built-in colors
  colorMap.value = filesCardRef.value?.colorMap;
  console.log(colorMap.value);
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <span>Set name property, and name has no suffix. name="Test File"</span>
    <FilesCard ref="filesCardRef" name="Test File" />
    <span>Set name property, has file suffix. name="Test File.pdf"</span>
    <FilesCard name="Test File.pdf" />
    <span>Supports matching built-in icons based on name suffix </span>
    <div class="files-card-container">
      <FilesCard name="Test doc suffix.doc" />
      <FilesCard name="Test xls suffix.xls" />
      <FilesCard name="Test ppt suffix.ppt" />
      <FilesCard name="Test txt suffix.txt" />
      <FilesCard name="Test pdf suffix.pdf" />
      <FilesCard name="Test png suffix.png" />
      <FilesCard name="Test jpg suffix.jpg" />
      <FilesCard name="Test gif suffix.gif" />
      <FilesCard name="Test mp4 suffix.mp4" />
      <FilesCard name="Test mp3 suffix.mp3" />
      <FilesCard name="Test zip suffix.zip" />
      <FilesCard name="Test rar suffix.rar" />
      <FilesCard name="Test 7z suffix.7z" />
      <FilesCard name="Test lnk suffix.lnk" />
      <FilesCard name="Test obj suffix.obj" />
      <FilesCard name="Test fbx suffix.fbx" />
      <FilesCard name="Test glb suffix.glb" />
      <FilesCard name="Test sql suffix.sql" />
      <FilesCard name="Test db suffix.db" />
      <FilesCard name="Test md suffix.md" />
      <FilesCard name="Test js suffix.js" />
      <FilesCard name="Test py suffix.py" />
      <FilesCard name="Test java suffix.java" />
      <FilesCard name="Test php suffix.php" />
      <FilesCard name="Test json suffix.json" />
    </div>
    <span>If there is a suffix but can't match common icons, it defaults to
      File</span>
    <FilesCard name="https://dd.comMultiple special characters.suffix.self" />
  </div>
</template>

<style scoped lang="less">
.files-card-container {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}
</style>

Status Setting

Set status property to control file loading status "uploading","done","error"

uploading test file

.pdf

上传中...・0%

done test file

.pdf

Pdf

error test file

.pdf

上传失败

"uploading"+"percent" controls upload progress, "error"+"errorTip" controls custom failure prompt

uploading test file

.doc

上传中...・50%

error test file

.doc

Custom failure prompt

status and percent Properties

Control file loading status (uploading, completed, failed) and progress display.

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div class="files-card-container-wrapper">
      <span>Set status property to control file loading status
        "uploading","done","error"</span>
      <div class="files-card-container">
        <FilesCard name="uploading test file.pdf" status="uploading" />
        <FilesCard name="done test file.pdf" status="done" />
        <FilesCard name="error test file.pdf" status="error" />
      </div>
      <span>"uploading"+"percent" controls upload progress, "error"+"errorTip"
        controls custom failure prompt
      </span>
      <div class="files-card-container">
        <FilesCard
          name="uploading test file.doc"
          status="uploading"
          :percent="50"
        />
        <FilesCard
          name="error test file.doc"
          status="error"
          error-tip="Custom failure prompt"
        />
      </div>
    </div>
  </div>
</template>

<style scoped lang="less">
.files-card-container-wrapper {
  display: flex;
  gap: 12px;
  flex-direction: column;

  .files-card-container {
    display: flex;
    flex-wrap: wrap;
    gap: 8px;
  }
}
</style>

Display Delete Icon

Delete test file

.md

Markdown

Delete Icon, Delete Event

You can set the showDelIcon property to show the delete icon, and set the @delete method to handle the delete event.

<script setup lang="ts">
function handleDel() {
  ElMessage.success('Delete successful');
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <FilesCard name="Delete test file.md" show-del-icon @delete="handleDel" />
  </div>
</template>

<style scoped lang="less"></style>

Image File Display

Image files previewable and non-previewable

Previewable image

.jpeg

Image

Non-previewable image

.jpeg

Image

Image files square variant other formats are not affected by variant property

Other files not affected by variant

.txt

Txt・29 KB

Image files default rectangle variant supports upload status, supports preview on/off, supports preview mask overlay on/off

Upload progress

.jpeg

上传中...・50%

Upload failed

.jpeg

上传失败

Close preview hover mask

.jpeg

Image

Close preview function

.jpeg

Image

Image files square variant supports upload status, supports preview on/off, supports preview mask overlay on/off

50%

上传失败

Image File Section

Supports image preview, square/rectangle variants, upload status overlay and other features. Can also be controlled through status and percent.

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div class="files-card-container-wrapper">
      <span>Image files <span style="color: red">previewable</span> and
        <span style="color: red">non-previewable</span></span>
      <div class="files-card-container">
        <FilesCard
          name="Previewable image.jpeg"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard name="Non-previewable image.jpeg" show-del-icon />
      </div>
      <span>Image files
        <span style="color: red">square variant</span>
        other formats are not affected by variant property</span>
      <div class="files-card-container">
        <FilesCard
          name="Previewable image.jpeg"
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
          img-variant="square"
          show-del-icon
        />
        <FilesCard
          name="Non-previewable image.jpeg"
          img-variant="square"
          show-del-icon
        />
        <FilesCard
          name="Other files not affected by variant.txt"
          img-variant="square"
          show-del-icon
          :file-size="30000"
        />
      </div>
      <span>Image files default rectangle variant
        <span style="color: red">supports upload status, supports preview on/off, supports preview
          mask overlay on/off</span></span>
      <div class="files-card-container">
        <FilesCard
          name="Upload progress.jpeg"
          :percent="50"
          status="uploading"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Upload failed.jpeg"
          status="error"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Close preview hover mask.jpeg"
          :img-preview-mask="false"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Close preview function.jpeg"
          :img-preview="false"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
      </div>

      <span>Image files square variant
        <span style="color: red">supports upload status, supports preview on/off, supports preview
          mask overlay on/off</span></span>
      <div class="files-card-container">
        <FilesCard
          name="Upload progress.jpeg"
          img-variant="square"
          :percent="50"
          status="uploading"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Upload failed.jpeg"
          img-variant="square"
          status="error"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Upload completed.jpeg"
          img-variant="square"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Close preview hover mask.jpeg"
          img-variant="square"
          :img-preview-mask="false"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
        <FilesCard
          name="Close preview function.jpeg"
          img-variant="square"
          :img-preview="false"
          show-del-icon
          url="https://avatars.githubusercontent.com/u/76239030?v=4"
        />
      </div>
    </div>
  </div>
</template>

<style scoped lang="less">
.files-card-container-wrapper {
  display: flex;
  gap: 12px;
  flex-direction: column;
  .files-card-container {
    display: flex;
    flex-wrap: wrap;
    gap: 8px;
  }
}
</style>

Custom Styles and Interaction

Custom style

.xls

Excel

Custom hoverStyle

.xls

Excel

Custom Styles

Customize card styles via style/hoverStyle, supports hover delete icon and custom slot extension.

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <FilesCard
      name="Custom style.xls"
      style="
        background-color: #f0f9eb;
        border: 2px solid #67c23a;
        border-radius: 20px;
      "
    />
    <FilesCard
      name="Custom hoverStyle.xls"
      style="
        background-color: #f0f9eb;
        border: 1px solid #67c23a;
        border-radius: 20px;
      "
      :hover-style="{
        'box-shadow': '0 2px 12px 0 rgba(0, 0, 0, 0.1)',
        'border-color': 'red',
        'background-color': 'rgba(255, 0, 0, 0.1)'
      }"
    />
  </div>
</template>

<style scoped lang="less"></style>

Custom Built-in File Colors

Custom Colors 1

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Custom Colors 2

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Test Name

Test description

Custom Built-in File Colors

<script setup lang="ts">
import type {
  FilesCardProps,
  FilesType
} from 'vue-element-plus-x/types/FilesCard';

// Custom file colors 1
const colorMap1: Record<FilesType, string> = {
  word: '#5E74A8',
  excel: '#4A6B4A',
  ppt: '#C27C40',
  pdf: '#5A6976',
  txt: '#D4C58C',
  mark: '#FFA500',
  image: '#8E7CC3',
  audio: '#A67B5B',
  video: '#4A5568',
  three: '#5F9E86',
  code: '#4B636E',
  database: '#4A5A6B',
  link: '#5D7CBA',
  zip: '#8B5E3C',
  file: '#AAB2BF',
  unknown: '#888888'
};

// Custom file colors 2
const colorMap2: Record<FilesType, string> = {
  word: '#0078D4',
  excel: '#4CB050',
  ppt: '#FF9933',
  pdf: '#E81123',
  txt: '#666666',
  mark: '#FFA500',
  image: '#B490F3',
  audio: '#00B2EE',
  video: '#2EC4B6',
  three: '#00C8FF',
  code: '#00589F',
  database: '#F5A623',
  link: '#007BFF',
  zip: '#888888',
  file: '#F0D9B5',
  unknown: '#D8D8D8'
};

type ColorKey = keyof typeof colorMap1;
const colorKeys = computed(() => Object.keys(colorMap1) as ColorKey[]);

const filesCardProps = ref<FilesCardProps>({
  uid: '1',
  name: 'Test Name',
  description: 'Test description'
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div class="files-card-container-wrapper">
      <p>Custom Colors 1</p>
      <div class="files-card-container">
        <FilesCard
          v-for="items in colorKeys"
          :key="items"
          v-bind="{ ...filesCardProps }"
          :icon-color="colorMap1[items]"
          :file-type="items"
        />
      </div>
      <p>Custom Colors 2</p>
      <div class="files-card-container">
        <FilesCard
          v-for="items in colorKeys"
          :key="items"
          v-bind="{ ...filesCardProps }"
          :icon-color="colorMap2[items]"
          :file-type="items"
        />
      </div>
    </div>
  </div>
</template>

<style scoped lang="less">
.files-card-container-wrapper {
  display: flex;
  gap: 12px;
  flex-direction: column;
  .files-card-container {
    display: flex;
    flex-wrap: wrap;
    gap: 8px;
  }
}
</style>

Properties

Property Name	Type	Required	Default	Description
uid	string | number	No	undefined	File unique identifier
name	string	No	undefined	File name (supports automatic suffix parsing to match icons)
fileSize	number	No	undefined	File size (unit: bytes, automatically converted to readable format)
fileType	string	No	undefined	File type (priority higher than name suffix parsing, e.g. 'image', 'document')
description	string	No	undefined	Description text (supports dynamic generation of file type and size info)
url	string	No	undefined	File access URL (image files can be used for preview)
thumbUrl	string	No	undefined	Image thumbnail URL
imgFile	File | Blob	No	undefined	Image file stream (automatically parsed as preview URL, only for temporary display before upload)
iconSize	string	No	'42px'	Icon/image size
iconColor	string	No	undefined	Icon color for non-image files (supports custom color values)
showDelIcon	boolean	No	false	Whether to show hover delete icon
maxWidth	string	No	'236px'	Card maximum width
style	CSSProperties	No	undefined	Card custom styles
hoverStyle	CSSProperties	No	undefined	Card custom styles when hovering
imgVariant	'rectangle' | 'square'	No	'rectangle'	Image card form (rectangle/square)
imgPreview	boolean	No	true	Whether to enable image preview functionality
imgPreviewMask	boolean	No	true	Whether to show image preview mask overlay
status	'uploading' | 'done' | 'error'	No	undefined	File status (controls progress bar, error prompts and other visual feedback)
percent	number	No	0	Upload progress percentage (used with status="uploading")
errorTip	string	No	'Upload failed'	Custom error status prompt text

Slots

Slot Name	Slot Parameters	Description
#icon	{ item: FilesCardProps }	Custom icon area (priority higher than auto-parsed built-in icons)
#content	{ item: FilesCardProps }	Custom content area (overrides default name and description display)
#name-prefix	{ item: FilesCardProps, prefix, suffix }	Custom file name prefix (for truncation display scenarios)
#name-suffix	{ item: FilesCardProps, prefix, suffix }	Custom file name suffix (for truncation display scenarios)
#description	{ item: FilesCardProps, prefix, suffix }	Custom description text (overrides default generated description)
#image-preview-actions	{ item: FilesCardProps, prefix, suffix }	Image preview mask content (displayed on hover, requires imgPreviewMask)
#del-icon	{ item: FilesCardProps }	Custom delete icon (default uses Element Plus CircleCloseFilled icon)

Events

Event Name	Callback Parameters	Description
delete	{ ...props }	Triggered when delete button is clicked, passes complete properties of current card
image-preview	{ ...props }	Called when image preview function is triggered (click image or mask layer)

Features

1. Automatic File Type Recognition Automatically matches built-in icons based on file name suffixes (supports common formats like .pdf, .png, .zip, etc.), displays generic file icon when no match is found.
2. Multi-state Visualization Supports uploading (uploading with progress bar), done (completed), error (failed with custom prompt) three states, state styles automatically switch.
3. Enhanced Image File Support Supports image preview functionality (based on Element Plus image preview component), provides square/rectangle variants, supports direct parsing of local image file streams through imgFile.
4. Highly Customizable Custom icon colors, sizes, card styles and hover effects, flexibly extend content through slots (such as file name truncation display, status overlay).
5. Responsive Design Supports controlling card maximum width through maxWidth, adapts to different layout scenarios, file descriptions automatically truncate to prevent overflow.