Media Fields for Contact Form 7

1. Getting started

This guide takes you from an empty site to a working video field inside a form. It takes about five minutes.

1.1 Install the plugin

In your WordPress admin go to Plugins → Add New and search for Media Fields for Contact Form 7. Click Install Now, then Activate.

If Contact Form 7 is not installed yet, WordPress asks you to install it first — the plugin needs it to work.

You can also upload the zip from the plugin page: Plugins → Add New → Upload Plugin.

1.2 Activate it

After activation the plugin appears in your plugin list with three links: Settings, Opt In and Deactivate.

1.3 The one-time opt-in

The first time you open the plugin you are asked, once, whether you would like to share some non-sensitive data about your site: the WordPress and PHP versions, the active plugins, and which of the media fields you use. It helps us decide which fields to build next.

• Allow & Continue — share the data.
• Skip — share nothing. The plugin works exactly the same.

Nothing is sent unless you allow it, and you can change your mind at any time from the Opt In / Opt Out link on the Plugins screen.

1.4 The dashboard

After that you land on the plugin's dashboard: Contact → Media Fields.

The dashboard has:

• Watch and learn — two short videos, a step-by-step tutorial and a two-minute introduction. Nothing is requested from YouTube until you press play. Hide videos collapses the panel and remembers your choice.
• Overview — a card for each field type with an on/off switch and a Configure button.
• The left menu — one page of defaults per field type, plus General and a Tag reference with copy-and-paste examples.

You do not need to change anything here to start. The defaults are sensible. Come back when you want to set a brand colour or a default layout for every form at once — see Settings.

1.5 Build your first field

Open a form: Contact → Contact Forms, then click a form or Add New.

Above the form editor is a row of tag buttons. The last five are the media fields: video, audio, 3D model, gallery and PDF.

Click video. A tag generator opens.

1. Field name — type a short name, for example intro.
2. Media source — paste a video URL. This can be a file on your site, a YouTube link or a Vimeo link. Add from Media Library picks a file you have already uploaded.
3. Title — optional. Used for accessibility and shown on the lock screen on phones.
4. The sections below (Layout, Playback, Controls, and so on) are optional. Open any of them to change how the player looks or behaves. Only the options you change are written into the tag.
5. Click Insert Tag.

The tag appears in your form where the cursor was:

[video intro "https://example.com/intro.mp4"]

Put it wherever you want the player to appear — above the fields, between them, next to the submit button. Save the form.

1.6 Put the form on a page

Every Contact Form 7 form has a shortcode. It is at the top of the form editor:

Copy it and paste it into any page or post. In the block editor use a Shortcode block or the Contact Form 7 block.

Open the page. The video plays inside the form:

1.7 What next

• Add the other fields the same way: audio, 3D models, galleries, PDF flipbooks.
• Set defaults once for every form in Settings.
• If something does not look right, see FAQ and troubleshooting.

Nothing is sent with the email. Media fields display content; they do not collect anything. That is why they do not appear in the Mail tab and why the generator says "This tag has no user input, so there is no mail-tag for it."

2. Video field

Plays a video inside the form. Works with files on your own site (MP4, WebM, Ogg), YouTube and Vimeo. The player is Plyr, a lightweight, accessible player, and every Plyr option is available as a tag option.

2.1 Quick start with the generator

In the form editor click video.

• Field name — required, for example tour.
• Provider — leave on Self-hosted for a file, or pick YouTube / Vimeo. The plugin also detects YouTube and Vimeo links automatically, so you can usually leave this alone.
• Media URL(s) — one URL per line. For self-hosted video you can add several files (for example MP4 and WebM) and the browser picks the one it supports.
• Title — optional.

Everything else is optional. Click Insert Tag.

2.2 Examples

A file on your site:

[video intro "https://example.com/intro.mp4"]

A YouTube video, privacy-enhanced (no cookies until play):

[video promo yt-nocookie "https://www.youtube.com/watch?v=bTqVqk7FSmY"]

A Vimeo video that starts muted and loops, using just the video ID:

[video promo provider:vimeo autoplay muted loop "76979871"]

A 16:9 player with a poster image, a brand colour and a title:

[video tour poster:https://example.com/poster.jpg ratio:16:9 color:#146EF5 "https://example.com/tour.mp4"] Inside the studio [/video]

Quality switching — one file per quality with a size hint after a pipe:

[video intro quality:720 "https://example.com/intro-1080.mp4|1080" "https://example.com/intro-720.mp4|720"]

2.3 Rules worth knowing

• URLs go last and in double quotes.
• Option values cannot contain spaces. Use _ for a space in text (artist:Jane_Doe) and | to separate list items.
• Autoplay only works when the video is also muted. That is a browser rule, not a plugin one.
• A bare word is a flag: autoplay, muted, loop. A no- flag turns something off even if the settings page turns it on: no-fullscreen.

2.4 All options

Source

Layout and appearance

Playback

Controls and settings menu

Example — a minimal player with only play, progress and fullscreen:

[video clip controls:play|progress|fullscreen "https://example.com/clip.mp4"]

Interface behaviour

Captions

Captions work with WebVTT (.vtt) files for self-hosted video. For YouTube they set the caption preference of the embedded player.

[video talk captions:en|https://example.com/en.vtt|English fr|https://example.com/fr.vtt|Français captions-active "https://example.com/talk.mp4"]

If the caption file lives on another domain add the crossorigin flag.

Speed and quality

Quality switching for your own files needs one source per quality with a size hint: "video-720.mp4|720".

Lock-screen information (phones)

Chapters and preview thumbnails

YouTube

Vimeo

Advanced

2.5 Site-wide defaults

The accent colour, the default control set, the settings menu, "remember visitor preferences" and "auto-hide controls" can be set once for every video in Contact → Media Fields → Video. A tag option always wins over the default. See Settings.

3. Audio field

Plays an audio file inside the form: MP3, M4A, AAC, OGG, WAV or FLAC. Good for a podcast episode above a question form, a voice message on a booking form, or a sample track on an order form.

3.1 Quick start with the generator

In the form editor click audio.

• Field name — required, for example episode.
• Media URL(s) — one URL per line. Add several formats if you have them; the browser picks one it can play. Add from Media Library picks an uploaded file.
• Title — optional. Shown on the lock screen on phones.

Click Insert Tag.

3.2 Examples

[audio episode "https://example.com/episode-4.mp3"]

With a title, artist name and brand colour:

[audio brief artist:Nocturne_Studio color:#FF7A00 "https://example.com/brief.mp3"] Episode 4 — Colour in the dark [/audio]

Two formats, so every browser can play it:

[audio jingle "https://example.com/jingle.mp3" "https://example.com/jingle.ogg"]

3.3 Options

The audio field uses the same player as the video field, so every option in Video → All options also works here. The ones that matter most for audio:

Options that only make sense for pictures — ratio:, poster:, captions, fullscreen, picture-in-picture, YouTube and Vimeo options — are ignored.

3.4 Site-wide defaults

Contact → Media Fields → Audio sets the accent colour, the default controls, the settings menu and the behaviour switches for every audio player at once. See Settings.

4. 3D model field

Shows an interactive 3D model inside the form. Visitors drag to spin it, scroll to zoom, and on a phone can place it in their own room with augmented reality. Useful for product enquiries, made-to-order items and anything people want to inspect before they ask.

The viewer is Google's <model-viewer>, and every one of its options is available.

4.1 What you need

• A model in glTF or GLB format (.glb is a single file and the easiest to work with).
• Optionally a USDZ file of the same model for augmented reality on iPhones and iPads.

While the 3D field is enabled, the Media Library accepts .glb, .gltf, .usdz and .hdr uploads, so you can upload models like any other file. Free sample models to try: https://modelviewer.dev/shared-assets/.

4.2 Quick start with the generator

In the form editor click 3D model.

• Field name — required, for example product.
• Model URL — the .glb or .gltf file. Put a .usdz file on a second line for iOS augmented reality. Add from Media Library picks an uploaded model.
• Title / accessible description — used as the alt text, for example "A red armchair".

The sections below (Layout, Camera, Augmented reality, Lighting, Animation, Hotspots) are optional. Click Insert Tag.

4.3 Examples

The simplest tag:

[3d_models product "https://example.com/chair.glb"]

Spinning slowly, with the AR button and an iOS file:

[3d_models chair auto-rotate ar "https://example.com/chair.glb" "https://example.com/chair.usdz"] Red armchair [/3d_models]

A product shot: soft shadow, studio lighting, a pale background, two labelled hotspots and a custom AR button:

[3d_models product auto-rotate ar camera-orbit:28deg|74deg|auto shadow-intensity:1 shadow-softness:0.6 environment:neutral exposure:1.15 height:470 bg:#F2F7FF hotspot:0|0.75|0.25|Hand_finished_top hotspot:0.75|-0.16|0|Solid_oak_core ar-button-label:View_in_your_room "https://example.com/plinth.glb"] The Plinth [/3d_models]

4.4 Rules worth knowing

• Values with several parts use |: camera-orbit:0deg|75deg|105% becomes 0deg 75deg 105%.
• Lengths accept m, cm, mm, deg, rad, % or auto.
• Use _ for a space in labels: Hand_finished_top.
• The first non-USDZ URL is the model; the first .usdz URL is used for iOS.

4.5 All options

Layout and appearance

Loading

Camera and interaction

Augmented reality

Lighting and environment

Animation and variants

Hotspots

A hotspot is a labelled dot pinned to a point on the model.

[3d_models chair hotspot:0|0.5|0.2|Handle hotspot:-0.3|0.1|0|Base_plate "https://example.com/chair.glb"]

To find coordinates, open the model at https://modelviewer.dev/editor/, click the surface and read the position.

Advanced

4.6 Site-wide defaults

Contact → Media Fields → 3D Models sets the default height, colours, camera controls, auto-rotate, the interaction prompt, AR, lighting, tone mapping, exposure, shadow and loading strategy. See Settings.

5. Image gallery field

Shows a set of images inside the form: as a grid, a masonry wall, justified rows or a carousel, with captions and a lightbox. Show recent work above an enquiry form, product photos above an order form, or room pictures above a booking form.

5.1 Quick start with the generator

In the form editor click gallery.

• Field name — required, for example work.
• Images — one URL per line. Add from Media Library lets you pick several images at once. To add a caption, put it after a pipe on the same line: https://example.com/a.jpg|Aurora No. 3.
• Open the Layout section to choose Grid, Masonry, Justified rows or Carousel, and Captions & lightbox / Carousel options for the rest.

Click Insert Tag.

5.2 Examples

A three-column grid with captions:

[gallery work columns:3 gap:14 ratio:4:3 captions "https://example.com/art-1.jpg|Aurora No. 3" "https://example.com/art-2.jpg|Ember Study" "https://example.com/art-3.jpg|Verdant"]

A carousel showing two slides at a time:

[gallery slides layout:carousel columns:2 height:378 gap:16 captions "https://example.com/a.jpg|Ember Study — 120 × 90 cm" "https://example.com/b.jpg|Nocturne — 100 × 100 cm"]

A carousel that advances on its own every five seconds:

[gallery portfolio layout:carousel autoplay interval:5 "https://example.com/a.jpg" "https://example.com/b.jpg"]

5.3 The lightbox

Clicking an image opens it full size with previous / next arrows and a counter. It is on by default; add no-lightbox to turn it off for one gallery, or switch it off for all galleries in Settings.

5.4 Rules worth knowing

• Captions are the one place spaces are allowed, because the whole value is in quotes. Everything after the first | is the caption.
• The caption is also used as the image's alt text.
• The gallery has no closing tag; text between [gallery] and [/gallery] is ignored.

5.5 All options

Layout

Captions and lightbox

Carousel only

Advanced

5.6 Site-wide defaults

Contact → Media Fields → Image Gallery sets the default layout, columns, gap, thumbnail ratio, row height, lightbox and captions. See Settings.

Note: when Show captions is switched on in Settings it applies to every gallery; there is no per-gallery option to hide them again. Leave the setting off and add the captions flag to the galleries that need it.

6. PDF flipbook field

Shows a PDF inside the form, either as a book whose pages turn, or as pages stacked one under the other. Visitors can zoom, go fullscreen and, if you allow it, download the file. Good for catalogues, brochures, price lists and menus that you want people to read before they fill in the form.

6.1 Quick start with the generator

In the form editor click PDF.

• Field name — required, for example catalogue.
• PDF URL — the file. Select from Media Library picks an uploaded PDF.
• Loading text — optional; shown while the document loads.
• Open the Layout and Viewer sections for size, Flipbook or Scroll mode, start page and the toolbar buttons.

Click Insert Tag.

6.2 Examples

[pdf_flipbook brochure "https://example.com/brochure.pdf"]

A taller viewer that loads straight away and allows download:

[pdf_flipbook catalogue height:560 eager download "https://example.com/catalogue.pdf"] Loading the catalogue… [/pdf_flipbook]

Scrolling pages, opening on page 3, no toolbar:

[pdf_flipbook terms mode:scroll start-page:3 no-toolbar "https://example.com/terms.pdf"]

6.3 Rules worth knowing

• Only the first URL is used.
• The PDF is loaded when it scrolls into view, so a long page with a flipbook near the bottom does not download the file until needed. Add eager to load it immediately.
• The download button is hidden by default so the document stays inside your page. Add download to show it.
• Large PDFs render page by page; the first page appears as soon as it is ready.

6.4 All options

Layout

Viewer

Toolbar

Advanced

6.5 Site-wide defaults

Contact → Media Fields → PDF Flipbook sets the default height, background, mode, page-turn duration and whether the toolbar shows. See Settings.

7. Settings

Contact → Media Fields holds the site-wide defaults. Set something here once and every form uses it; a tag option in one form always overrides the default for that form only.

7.1 Overview

The Overview page shows one card per field type. Each card has:

• an on/off switch — switch a field type off and its tags render nothing for visitors (editors see a small notice in the form editor instead), and its assets are no longer loaded;
• a Configure button that jumps to that field's defaults.

Below the cards, Watch and learn holds the two tutorial videos. Hide videos collapses the panel; the choice is remembered per user.

Click Save changes after any change. An unsaved-changes hint appears next to the button when something differs from what is stored.

7.2 Video

7.3 Audio

Same settings as Video, with the choices narrowed to what makes sense for audio. Default controls: play, progress, current time, mute, volume, settings. Default settings menu: speed.

7.4 3D Models

7.5 Image Gallery

7.6 PDF Flipbook

7.7 General

7.8 Tag reference

A read-only cheat sheet with one working example per field type and the ordering rules, for copying into a form.

8. FAQ and troubleshooting

General

Do media fields send anything with the email? No. They display content; they collect nothing. That is why they are not offered in the Mail tab and the generator says there is no mail-tag.

Why does the field need a name if nothing is submitted? Contact Form 7 requires every form-tag to have a name. Any name will do.

Can I put more than one media field in a form? Yes, as many as you like, of any type. See the "Commission enquiry" form on the demo site, which combines a video and a gallery.

Does the plugin load anything from other servers? No. The players and viewers (Plyr, model-viewer, PDF.js, StPageFlip) are bundled with the plugin and served from your site. YouTube and Vimeo videos naturally come from YouTube and Vimeo, and only once a visitor presses play (or immediately, if you set autoplay).

Does it work with page builders? Yes, wherever the Contact Form 7 shortcode works. If a player appears unstyled inside a builder or a popup, turn on Load assets on every page in Settings → General.

The form editor

The tag I typed shows as plain text on the page. Check the order: type, name, options, then the quoted URL(s) last. A URL before an option breaks the tag. Use the generator to avoid this.

The tag renders nothing at all. The field type may be switched off in Contact → Media Fields → Overview. Editors see a notice in the editor; visitors see nothing.

"Add from Media Library" closes the tag generator. That is expected. Contact Form 7's dialog sits above everything else, so the plugin closes it while the Media Library is open and reopens it, with your values intact, when you are done.

I cannot upload a .glb / .usdz file. Make sure the 3D field is enabled in Settings. Uploads of .glb, .gltf, .usdz and .hdr are allowed only while it is.

Video and audio

Autoplay does not work. Browsers only allow autoplay when the media is muted. Use autoplay muted together.

The quality menu is empty. Quality switching for your own files needs one file per quality with a size hint: "video-720.mp4|720" "video-1080.mp4|1080". YouTube and Vimeo manage quality themselves.

Captions do not show. Captions need WebVTT (.vtt) files. If the file is on another domain, add the crossorigin flag and make sure that server sends CORS headers.

A YouTube video says "Error 153" or "Video player configuration error". Your site sends a strict Referrer-Policy header (often same-origin), so YouTube cannot see which site is embedding the video. The plugin sets the correct policy on its own players, but if you embed YouTube some other way on the same page that embed will still fail. The fix at the source is to set the site's policy to strict-origin-when-cross-origin.

The video is huge / tiny. Set width: for a maximum width, or ratio: to control the shape. The player is always as wide as the form unless you limit it.

3D models

The model is cropped or off-centre. Use camera-orbit: with auto for the radius, for example camera-orbit:0deg|75deg|auto, or set camera-target:auto|auto|auto. You can also try bounds:tight.

The model is dark. Add environment:neutral and raise exposure: (try 1.2).

The AR button does not appear on iPhone. iOS needs a USDZ file. Add it as a second URL or with ios-src:.

Hotspots are in the wrong place. Positions are in metres in the model's own coordinate system. Open the model at https://modelviewer.dev/editor/, click the surface and copy the coordinates shown.

Gallery

I turned on captions in Settings and now every gallery has them. The setting applies to every gallery, and there is no per-gallery option to remove them. Turn the setting off and add the captions flag only to the galleries that need it.

Images are cropped. Add contain to fit the whole image, or set ratio: to match your images, or leave ratio: empty for the original shape.

Tiles are uneven in a grid. Set a ratio: — the grid uses it to keep every tile the same shape.

PDF flipbook

The PDF does not load. Check that the URL opens in a browser tab on its own. The file must be served over http or https from a server that allows it to be read (same site is always fine).

I want visitors to be able to download it. Add the download flag. It is hidden by default.

The pages look blurry. Zoom in with the toolbar; pages re-render at the new size. Very small viewers can be enlarged with height:.

Privacy and the opt-in

What does the opt-in share? WordPress and PHP versions, the active plugins and which media fields you use, through Freemius. Nothing is shared unless you allow it, and you can opt out from the Plugins screen at any time. See https://freemius.com/privacy/.

Still stuck?

Ask on the support forum: https://wordpress.org/support/plugin/b-media-fields-for-cf7/. Include the tag you used and, if possible, a link to the page.

9. For developers

The plugin is built around a schema for each field type, so most customisation is a filter away.

Filters

Example: force a control set on every video

add_filter( 'bmfcf7_player_config', function ( $config, $tag, $provider ) {
    if ( 'video' === $tag->basetype ) {
        $config['controls'] = array( 'play', 'progress', 'fullscreen' );
    }
    return $config;
}, 10, 3 );

Example: add a tone-mapping default for all models

add_filter( 'bmfcf7_model_viewer_atts', function ( $atts, $tag ) {
    if ( empty( $atts['tone-mapping'] ) ) {
        $atts['tone-mapping'] = 'aces';
    }
    return $atts;
}, 10, 2 );

Markup

Every field is wrapped in a div.bmfcf7-player-wrap carrying a data-name attribute with the field name, plus type-specific classes you can style against:

align:center / align:right add bmfcf7-align-center / bmfcf7-align-right. Anything given in a class: option is added to the same wrapper, and id: sets its id.

Assets

Player scripts and styles are enqueued only on pages where a form contains a media field, unless Load assets on every page is on. Bundled libraries and versions:

Source

The plugin is developed in the open: https://github.com/bPlugins/b-media-fields-for-cf7. Issues and pull requests are welcome.