> For the complete documentation index, see [llms.txt](https://docs.uichemy.com/llms.txt).
> Use it to discover all available pages before exploring further.

# ACF Custom Fields

Bind Advanced Custom Fields values to Elementor widgets via dynamic tags, and access ACF fields in Twig expressions inside a Composer widget.


Advanced Custom Fields (ACF) is the most widely used custom fields plugin for WordPress. UiChemy integrates with it two ways: dynamic tags for binding ACF values to standard Elementor widget controls, and Twig expressions for outputting ACF values anywhere in a Composer widget's HTML.

<Callout kind="info">
The **ACF dynamic tags** (no-code panel) require Advanced Custom Fields (free or Pro) to be installed and active, plus **UiChemy Pro**, they only appear in Elementor when ACF is active. Reading the same fields via **`post.meta()` in Twig** only requires Pro, it works even with ACF deactivated, since ACF fields are stored as plain post meta underneath, ACF just improves the formatting when it's active (for example, coercing an Image field into an array).
</Callout>

### ACF Dynamic Tags

Dynamic tags let you bind an ACF field value to any Elementor widget control that accepts dynamic data, headings, text editors, image controls, URL fields. No code required.

In the Elementor panel, look for the dynamic tag icon on any field that supports dynamic data. Click it and choose from the ACF group.

| Tag | Use for |
|---|---|
| ACF Field | Any text, textarea, number, date, select, checkbox, wysiwyg, color field |
| ACF URL | URL, link, page_link, or file fields (outputs the URL string) |
| ACF Image | Image fields (binds to image controls) |
| ACF Gallery (first image) | Gallery fields, outputs a specific image by index |

**Source option.** The ACF Field and ACF URL tags have a **Source** setting:

| Source | What it reads |
|---|---|
| Post | The field value on the current post |
| Post Author | The field value on the current post's author (user meta) |

**Supported field types.** The ACF Field tag supports: text, textarea, number, email, url, password, wysiwyg, select, checkbox, radio, button_group, true_false, range, date_picker, date_time_picker, time_picker, color_picker. For checkbox and multi-select fields that return arrays, the tag joins the selected values with a comma.

**ACF Gallery image index.** Includes an **Image Index** setting (default: 0). Set it to 0 for the first image, 1 for the second, and so on.

### ACF Fields in Twig

Inside a Composer widget's HTML panel (Developer Mode), output ACF field values using `post.meta()`:

```twig
{{ post.meta('field_name') }}
```

Replace `field_name` with the ACF field name (the name you set when creating the field, not the field key like `field_abc123`).

**Text and simple fields:**

```twig
<p class="product-tagline">{{ post.meta('tagline') }}</p>
<span class="price">{{ post.meta('custom_price') }}</span>
<a href="{{ post.meta('external_link') }}">Learn More</a>
```

**Conditional output:**

```twig
{% if post.meta('show_badge') %}
  <span class="badge">{{ post.meta('badge_text') }}</span>
{% endif %}

{% if post.meta('discount_percent') %}
  <span class="discount">{{ post.meta('discount_percent') }}% Off</span>
{% endif %}
```

**Author fields.** For user-attached ACF fields, chain to the author object:

```twig
{{ post.author.meta('certifications') }}
{{ post.author.meta('linkedin_url') }}
```

**Image fields.** ACF image fields return an array (or an ID, depending on the Return Format setting). Use `post.meta()` to get the ID and reference the attachment:

```twig
{# If Return Format is set to ID #}
{% set headshot_id = post.meta('author_headshot') %}
{% if headshot_id %}
  <img src="{{ headshot_id|wp_image_src('medium') }}" alt="{{ post.author.name }}">
{% endif %}

{# If Return Format is set to URL (simplest) #}
<img src="{{ post.meta('author_headshot_url') }}" alt="{{ post.author.name }}">
```

For simpler image binding in Elementor, use the ACF Image dynamic tag instead.

**Repeater and complex fields.** For ACF repeater fields, the raw `post.meta()` call returns the PHP array structure, use a `{% for %}` loop:

```twig
{% for row in post.meta('team_members') %}
  <div class="team-card">
    <h3>{{ row.name }}</h3>
    <p>{{ row.role }}</p>
  </div>
{% endfor %}
```

For complex nested ACF structures (flexible content, relational fields), the dynamic tag approach is usually simpler.

### Use Cases

- **A client-editable content field**, like a testimonial quote or a case study's client name, stored in ACF and rendered live in a Composer widget.
- **Binding an ACF field with no code**, via the dynamic tags panel, for standard field types.
- **Outputting a complex ACF field type**, a gallery or repeater, through Twig's `post.meta()` when the panel's dynamic tags aren't enough.

### Frequently Asked Questions

<ExpandableGroup>
  <Expandable title="Does UiChemy work with ACF Free or only ACF Pro?" default-open="false">
    Both. The dynamic tags and Twig integration work with ACF Free. Pro-only field types (repeater, flexible content, options pages) are accessible via `post.meta()` in Twig but may have complex data structures.
  </Expandable>

  <Expandable title="Can I use ACF options page values?" default-open="false">
    Options page fields are stored as user/option meta, not post meta. Use `site.option('field_key')` in Twig for options page fields, or access them via the ACF PHP API in a custom code block.
  </Expandable>

  <Expandable title="The ACF field dropdown is empty in the dynamic tag settings." default-open="false">
    This means either ACF is not active, or there are no field groups registered for the current post type. Check that your ACF field group is assigned to the correct post type in the ACF field group settings.
  </Expandable>
</ExpandableGroup>

### Related

<Columns cols={2}>
  <Card title="Dynamic Content Overview" href="/uichemy-composer/design-data/overview">
    See how ACF fits among the other data options.
  </Card>
  <Card title="Twig" href="/uichemy-composer/design-data/twig">
    Output a complex ACF field type Twig handles better.
  </Card>
  <Card title="Dynamic Tags" href="/uichemy-composer/design-data/dynamic-tags">
    See the no-code panel these ACF tags live in.
  </Card>
  <Card title="WooCommerce Data" href="/uichemy-composer/design-data/woocommerce-data">
    See the same pattern applied to product fields.
  </Card>
</Columns>