# Attach File

## Overview

<figure><img src="https://881612694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHbeJtpysoolkLI59NrC%2Fuploads%2FUUJRVdAxotl7UqE6dhdp%2FAttach%20File%202%20-%20Overview.png?alt=media&#x26;token=22b4daf8-7fe2-4e02-ab11-5eefd0efc12e" alt=""><figcaption></figcaption></figure>

## Usage

### **When to Use This Component**

Attach file fields are used in forms or other input scenarios where users need to provide files, such as documents, images, or other file types. They are ideal for applications that require file uploads as part of processes like submitting forms, attaching documents, or uploading images.

### **How It Works**

An attach file field component typically includes a label, a button to open the file picker dialog, and a display area to show the selected file name. Optional elements, such as placeholder text and helper text, can provide guidance to the user. The component can also display various states to reflect its status (e.g., focused, filled, error). The attach file field ensures users can easily select and upload files.

### Code

{% tabs %}
{% tab title="Vanilla Js" %}

```jsx
<dda-attach-file 
    label="Attach File"
    place_holder="No File Selected"
    upload_button_text="Choose File"
    helper_text="Helper or footer text"
    success_text="Successfully uploaded"
    error_message=""
    validation_id="validationId"
    file_size_error_message="File size should not exceed {max} MB"
    max_file_size="200"
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    delete_button_id="clearFile"
    aria_label="input"
    button_aria_label="button"
    button_name="button"
    input_name="input"
    accept=".pdf,.docx"
    oninput=""
></dda-attach-file>
```

{% endtab %}

{% tab title="React" %}

```jsx
<DdaAttachFile
    label="Attach File"
    place_holder="No File Selected"
    upload_button_text="Choose File"
    helper_text="Helper or footer text"
    success_text="Successfully uploaded"
    error_message=""
    validation_id="validationId"
    file_size_error_message="File size should not exceed {max} MB"
    max_file_size="200"
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    delete_button_id="clearFile"
    aria_label="input"
    button_aria_label="button"
    button_name="button"
    input_name="input"
    accept=".pdf,.docx"
    oninput=""
></DdaAttachFile>
```

{% endtab %}

{% tab title="Vue" %}

```jsx
<DdaAttachFile
    label="Attach File"
    place_holder="No File Selected"
    upload_button_text="Choose File"
    helper_text="Helper or footer text"
    success_text="Successfully uploaded"
    error_message=""
    validation_id="validationId"
    file_size_error_message="File size should not exceed {max} MB"
    max_file_size="200"
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    delete_button_id="clearFile"
    aria_label="input"
    button_aria_label="button"
    button_name="button"
    input_name="input"
    accept=".pdf,.docx"
    oninput=""
></DdaAttachFile>
```

{% endtab %}

{% tab title="Angular" %}

```jsx
<dda-attach-file
    label="Attach File"
    place_holder="No File Selected"
    upload_button_text="Choose File"
    helper_text="Helper or footer text"
    success_text="Successfully uploaded"
    error_message=""
    validation_id="validationId"
    file_size_error_message="File size should not exceed {max} MB"
    max_file_size="200"
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    delete_button_id="clearFile"
    aria_label="input"
    button_aria_label="button"
    button_name="button"
    input_name="input"
    accept=".pdf,.docx"
    oninput=""
></dda-attach-file>
```

{% endtab %}
{% endtabs %}

### Properties

| Property                  | Description                                                                                                                                                                       | Type     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `aria_label`              | The accessible label for the file input field.                                                                                                                                    | `string` |
| `button_aria_label`       | The accessible label for the remove file button.                                                                                                                                  | `string` |
| `button_id`               | The unique identifier for the upload file button.                                                                                                                                 | `string` |
| `delete_button_id`        | The unique identifier for the delete file button.                                                                                                                                 | `string` |
| `component_mode`          | Defines a mode for component behavior                                                                                                                                             | `string` |
| `custom_class`            | Additional CSS classes to apply for custom styling.                                                                                                                               | `string` |
| `error_message`           | An error message displayed if validation fails.                                                                                                                                   | `string` |
| `helper_text`             | A small helper message displayed below the file input for additional guidance.                                                                                                    | `string` |
| `input_id`                | The unique identifier for the file input field.                                                                                                                                   | `string` |
| `input_type`              | Specifies the type of input field styling (if applicable).                                                                                                                        | `string` |
| `label`                   | The label text displayed above the file input field.                                                                                                                              | `string` |
| `size`                    | Specifies the size of the input field.                                                                                                                                            | `string` |
| `validation_type`         | Determines the validation styling applied to the input (e.g., `'error'`, `'success'`).                                                                                            | `string` |
| `button_name`             | Name of the 'Choose File' button                                                                                                                                                  | `string` |
| `input_name`              | Name of the input field                                                                                                                                                           | `string` |
| `validation_id`           | The `validation_id="validationId"` attribute links the input field to a validation message element, helping with accessibility and displaying error or helper messages correctly. | `string` |
| `place_holder`            | Placeholder text shown when no file is selected.                                                                                                                                  | `string` |
| `upload_button_text`      | ext displayed on the file upload button.                                                                                                                                          | `string` |
| `success_text`            | Message shown upon successful file upload.                                                                                                                                        | `string` |
| `file_size_error_message` | Message shown when the uploaded file exceeds the maximum size. Use `{max}` as a placeholder for size in MB.                                                                       | `string` |
| `max_file_size`           | The maximum allowed file size in megabytes.                                                                                                                                       | `string` |
| `accept`                  | File types accepted for upload (e.g. `.pdf,.docx`).                                                                                                                               | `string` |
| `oninput`                 | JS handler called during file input (not typically recommended as string).                                                                                                        | `string` |

## Anatomy

<figure><img src="https://881612694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHbeJtpysoolkLI59NrC%2Fuploads%2FNjdd4BDjWdJRkNDFqIVw%2FAttach%20File%202%20-%20Anatomy.png?alt=media&#x26;token=15ca30cc-fbbd-4eb0-844f-3ff6181a156f" alt=""><figcaption></figcaption></figure>

### Anatomy Options

**Label**: Positioned above the file selection area, the label indicates the purpose of the component, prompting users to attach a file. It provides context for the file input field.

**Status Text**: Displays the current status of the file selection, such as "No File Selected" when no file has been chosen. This text updates to show the selected file name, helping users confirm their selection.

**Lead Icon**: Positioned to the left of the helper or footer text, the lead icon provides an additional visual cue, often indicating information or help related to the file attachment process.

**Caption**: Positioned below the file selection area, the caption provides additional information, instructions, or tips regarding the file upload, guiding users as they interact with the component.

**Button**: The main action button labeled "Choose File" initiates the file selection dialog. This button allows users to browse and select a file from their device for attachment.

### Dos and Don'ts

| Dos                                                                                                    | Don'ts                                                                           |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Use attach file fields to allow users to upload files in a standardized format.                        | Don't use attach file fields for text inputs or other non-file inputs.           |
| Label the attach file field clearly to indicate its purpose.                                           | Avoid using ambiguous or unclear labels for attach file fields.                  |
| Include placeholder text to guide users on the expected file format.                                   | Don't rely solely on placeholder text for essential instructions.                |
| Provide helper text to explain any specific file requirements or limitations.                          | Don't overload the attach file field with too much information.                  |
| Ensure the attach file button is large enough to be easily tappable or clickable.                      | Avoid making the attach file button too small to interact with comfortably.      |
| Validate the uploaded file and provide clear error messages when the file format or size is incorrect. | Don't provide generic error messages that don't help users understand the issue. |
| Keep consistent styling and spacing across all attach file fields in the application.                  | Don't use inconsistent styles that may confuse users.                            |