> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# Dynamic button

> Use Dynamic Button to provide a compact, state-aware upload entry point for the Regular File Uploader.

Dynamic Button is an alternative trigger for the Regular File Uploader. It replaces
the static upload button with a dynamic control that adapts to your configured
sources and current upload state.

Use it when the uploader should feel like a native part of a toolbar, form, chat
composer, profile editor, CMS field, or any other compact interface where a full
upload panel would take too much space.

## What it does

Dynamic Button combines source selection, drag and drop, upload progress, and
upload-list access in one control.

When no files are selected, it shows the first configured source as the primary
action and places the remaining sources inline or in a menu depending on the
selected view mode. After files are added, the primary action opens the upload
list, while the secondary action lets users cancel, remove failed uploads, or
clear uploaded files depending on the current state.

For example, with `source-list="local, camera, url, dropbox"`, the primary
button opens the local file picker and the other sources are available as
secondary actions.

## Enable Dynamic Button

Add the `dynamic-button` attribute to `uc-file-uploader-regular`.

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css"
/>

<script type="module">
  import * as UC from "https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.js";
  UC.defineComponents(UC);
</script>

<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY" source-list="local, camera, url, dropbox"></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

Dynamic Button is available for the Regular File Uploader. It uses the same
configuration, sources, validation, localization, upload list, and modal
behavior as the regular button.

## Configure the layout

Use `dynamic-button-view-mode` on `uc-config` to control how secondary sources are
shown.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, camera, url, dropbox"
  dynamic-button-view-mode="auto"
  dynamic-button-show-first-icon="true"
></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

| Option                           | Type                                 | Default | Description                                                                             |
| -------------------------------- | ------------------------------------ | ------- | --------------------------------------------------------------------------------------- |
| `dynamic-button-view-mode`       | `auto \| menu \| toolbar \| compact` | `auto`  | Controls how source actions are displayed.                                              |
| `dynamic-button-show-first-icon` | `boolean`                            | `true`  | Shows the first source icon inside the primary action when there are no selected files. |

The corresponding DOM properties are `dynamicButtonViewMode` and
`dynamicButtonShowFirstIcon`.

## View modes

### Auto

`auto` is the default mode. It shows secondary sources inline when there are up
to three configured sources. If there are more than three sources, it moves the
secondary sources into a dropdown menu.

Use `auto` for most product interfaces where the number of enabled sources can
vary by project or environment.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  dynamic-button-view-mode="auto"
  source-list="local, camera, url"
></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

### Menu

`menu` keeps the primary action visible and places all secondary sources in a
dropdown menu.

Use `menu` when the uploader sits inside a narrow area, but users still need a
clear default source.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  dynamic-button-view-mode="menu"
  source-list="local, camera, url, dropbox"
></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

### Toolbar

`toolbar` shows the primary action and all secondary sources inline.

Use `toolbar` when users frequently switch between sources and there is enough
horizontal space, such as an editor toolbar or internal admin UI.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  dynamic-button-view-mode="toolbar"
  source-list="local, camera, url"
></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

### Compact

`compact` shows a single paperclip-style menu button while idle and puts all
configured sources in the menu.

Use `compact` for dense interfaces such as chat attachments, comment boxes,
table cells, or mobile layouts.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  dynamic-button-view-mode="compact"
  source-list="local, camera, url, dropbox"
></uc-config>

<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>
```

## Source order

Dynamic Button uses the first item in `source-list` as the primary action, except
in `compact` mode where all sources are placed in the menu.

Choose the first source based on the action users are most likely to take:

```html
<!-- Local file picker is primary -->
<uc-config ctx-name="attachments" pubkey="YOUR_PUBLIC_KEY" source-list="local, camera, url"></uc-config>

<!-- Camera is primary -->
<uc-config ctx-name="profile-photo" pubkey="YOUR_PUBLIC_KEY" source-list="camera, local"></uc-config>
```

The primary action text is localized and depends on the source. Built-in source
labels include examples such as `Upload from device`, `Capture with camera`,
`Take photo`, and `Record video`.

## Use cases

### Attachment button in a chat or comment composer

Use `compact` mode with local, camera, and URL sources. Users get a small
paperclip-style button that still supports every configured source.

```html
<uc-config
  ctx-name="message-attachments"
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, camera, url"
  dynamic-button-view-mode="compact"
></uc-config>

<uc-file-uploader-regular ctx-name="message-attachments" dynamic-button></uc-file-uploader-regular>
```

### Profile photo upload

Use the camera as the primary source and keep local upload as a secondary
fallback.

```html
<uc-config
  ctx-name="avatar"
  pubkey="YOUR_PUBLIC_KEY"
  multiple="false"
  img-only="true"
  source-list="camera, local"
  dynamic-button-view-mode="menu"
></uc-config>

<uc-file-uploader-regular ctx-name="avatar" dynamic-button></uc-file-uploader-regular>
```

### CMS media field

Use `auto` mode so small source sets stay inline and larger source sets collapse
to a menu automatically.

```html
<uc-config
  ctx-name="cms-media"
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, url, dropbox, gdrive"
  dynamic-button-view-mode="auto"
></uc-config>

<uc-file-uploader-regular ctx-name="cms-media" dynamic-button></uc-file-uploader-regular>
```

### Admin toolbar

Use `toolbar` mode when operators frequently choose between device upload,
links, and cloud sources.

```html
<uc-config
  ctx-name="asset-toolbar"
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, url, dropbox"
  dynamic-button-view-mode="toolbar"
></uc-config>

<uc-file-uploader-regular ctx-name="asset-toolbar" dynamic-button></uc-file-uploader-regular>
```

## When to use Dynamic Button

Use Dynamic Button when:

* Uploading is part of a larger workflow and should not dominate the page.
* Users need quick access to multiple upload sources.
* You want the upload trigger to reflect selected, uploading, failed, and
  uploaded states.
* You need a compact attachment control with drag-and-drop support.

Use the default Regular File Uploader button when you want a simpler static
trigger and do not need source actions or upload state visible in the trigger
itself.