# capture-file

## Overview

{% hint style="info" %}
**Platform compatibility**

Compatible with all platforms. Web is only supported from version **4.80.0** of the JourneyApps Runtime.
{% endhint %}

{% hint style="info" %}
The `capture-file` component was visually updated in version **4.80.0** of JourneyApps Runtime.
{% endhint %}

The `capture-file` component allows users to upload a file from their device.

### Basic Example

{% code title="main.view\.xml" %}

```xml
<var name="current_file" type="attachment" media="application/pdf" />

<capture-file label="Upload signed document" bind="current_file" required="false" />
```

{% endcode %}

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-a6b21e7fc9e9dfc98e173f32dea9538f88d4c662%2Fcapture-file-example.png?alt=media)

## Standard Attributes

### `bind`

{% content-ref url="../xml-fields/bind" %}
[bind](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/bind)
{% endcontent-ref %}

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `required`

{% content-ref url="../xml-fields/required" %}
[required](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/required)
{% endcontent-ref %}

## Advanced Attributes

### `align-content`

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `align-controls`

{% content-ref url="../xml-fields/align-controls" %}
[align-controls](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-controls)
{% endcontent-ref %}

### `align-label`

{% content-ref url="../xml-fields/align-label" %}
[align-label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-label)
{% endcontent-ref %}

### `control-order`

{% content-ref url="../xml-fields/control-order" %}
[control-order](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/control-order)
{% endcontent-ref %}

### `disabled`

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `downloadable`

**Optional**

**Type**: `boolean`

**Default**: `true`

Set `downloadable` to `false` to hide the download button and prevent the user from downloading a captured/displayed file.

### `fullwidth`

**Optional**

**Type**: `boolean`

**Default**: `false`

Specify whether the file preview should span the full width of the available screen space.

{% tabs %}
{% tab title="capture-file" %}

```xml
<capture-file bind="report" label="Usage Report" fullwidth="true" />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-60ef521b1a64adff320d5b56bbe90809793c8f42%2Fcapture-file-fullwidth.png?alt=media)
{% endtab %}

{% tab title="display-file" %}

```xml
<display-file bind="report" label="Usage Report" fullwidth="true"/>
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-60ef521b1a64adff320d5b56bbe90809793c8f42%2Fcapture-file-fullwidth.png?alt=media)
{% endtab %}
{% endtabs %}

### `hide-filename`

**Optional**

**Type**: `boolean`

**Default**: `false`

Override the default and hide the captured/displayed filename from the preview.

{% tabs %}
{% tab title="capture-file" %}

```xml
<capture-file bind="report" label="Usage Report" hide-filename="true" />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-2d1cdaca6b4be48434e5516f3c03bdb3ed3376a7%2Fcapture-file-hide-filename.png?alt=media)
{% endtab %}

{% tab title="display-file" %}

```xml
<display-file bind="report" label="Usage Report" hide-filename="true" />
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-2d1cdaca6b4be48434e5516f3c03bdb3ed3376a7%2Fcapture-file-hide-filename.png?alt=media)
{% endtab %}
{% endtabs %}

### `icon-position`

{% hint style="info" %}
**Version compatibility**

`icon-position` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `label-case`

{% hint style="info" %}
**Version compatibility**

`label-case` was introduced in version **4.80.0** of the JourneyApps Runtime.
{% endhint %}

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `label-color`

{% content-ref url="../xml-fields/label-color" %}
[label-color](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-color)
{% endcontent-ref %}

### `on-change`

{% content-ref url="../xml-fields/on-change" %}
[on-change](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-change)
{% endcontent-ref %}

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id) is assigned to the component and `component.captureFile({id:'my-id'})` / `component.displayFile({id:'my-id'})` is called from JS/TS:

### `captureMedia`

Programmatically open the file picker that enables the user to select and upload a file.

```javascript
try {
    component.captureFile({id: 'my-id'}).captureMedia();
} catch (e) {
    // handle exception here
}
```

### `closeMedia`

Programmatically close the file preview.

{% tabs %}
{% tab title="capture-file" %}

```javascript
try {
    component.captureFile({id: 'my-id'}).closeMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}

{% tab title="display-file" %}

```javascript
try {
    component.displayFile({id: 'my-id'}).closeMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}
{% endtabs %}

### `deleteMedia`

Programmatically clear a captured file.

```javascript
try {
    component.captureFile({id: 'my-id'}).deleteMedia();
} catch (e) {
    // handle exception here
}
```

{% hint style="warning" %}
`deleteMedia` will trigger an [`on-change`](#on-change) if a function is assigned to it.
{% endhint %}

### `downloadMedia`

Programmatically trigger a download of the captured/displayed file.

{% tabs %}
{% tab title="capture-file" %}

```javascript
try{
    component.captureFile({id: 'my-id'}).downloadMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}

{% tab title="display-file" %}

```javascript
try {
    component.displayFile({id: 'my-id'}).downloadMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}
{% endtabs %}

### `getMetadata`

Retrieve metadata about the captured file.

```javascript
try {
    var data = component.captureFile({id: 'my-id'}).getMetadata();
    console.log('metadata', data);
} catch (e) {
    // handle exception here
}
```

### `openMedia`

Programmatically open the file preview.

{% tabs %}
{% tab title="capture-file" %}

```javascript
try {
    component.captureFile({id: 'my-id'}).openMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}

{% tab title="display-file" %}

```javascript
try {
    component.displayFile({id: 'my-id'}).openMedia();
} catch (e) {
    // handle exception here
}
```

{% endtab %}
{% endtabs %}

### `scrollIntoView`

Programmatically scroll until the `capture-file` / `display-file` component is visible in the view.

{% tabs %}
{% tab title="capture-file" %}

```javascript
try {
    component.captureFile({id: 'my-id'}).scrollIntoView();
} catch (e) {
    // handle exception here
}
```

{% endtab %}

{% tab title="display-file" %}

```javascript
try {
    component.displayFile({id: 'my-id'}).scrollIntoView();
} catch (e) {
    // handle exception here
}
```

{% endtab %}
{% endtabs %}