---
title: How to Customize the Markup and Styles (for Developers)
description: Easeful Themes for ACF builds every field group from a small set of PHP templates and one stylesheet, and you can override any template from your WordPress theme, restyle the output with CSS, or change it with a filter, while…
url: "https://htmgarcia.com/docs/customize-the-markup/"
updated: "2026-10-15"
category: Easeful Themes for ACF
---

# How to Customize the Markup and Styles (for Developers)

Easeful Themes for ACF builds every field group from a small set of PHP templates and one stylesheet, and you can override any template from your WordPress theme, restyle the output with CSS, or change it with a filter, while the theme settings keep working.

This article is for developers comfortable editing theme files. Everything here survives plugin updates, because your changes live in your own theme or plugin rather than in Easeful Themes for ACF.

## How the Output Is Built

A rendered field group is made of these templates, all in the plugin's `templates/` folder:

- `group.php` — the outer wrapper and its grid.
- `field-wrap.php` — one top-level field: its column, card and label.
- `content-wrap.php` — the post content, when it's placed among the fields in its 'Plain' style.
- `fields/field-{type}.php` — the value of one field, by type: `field-text.php` covers text, text area, email, URL, number and range; `field-choice.php` covers select, checkbox, radio and button group; `field-relational.php` covers post object, relationship and page link; and `field-date.php`, `field-image.php`, `field-gallery.php`, `field-file.php`, `field-link.php`, `field-oembed.php`, `field-color.php`, `field-wysiwyg.php`, `field-true-false.php`, `field-taxonomy.php`, `field-user.php`, `field-group.php`, `field-repeater.php` and `field-flexible-content.php` each cover the type in their name.
- `fields/field-default.php` — every other field type.

## How to Override a Template

1. Create a `easeful-themes-for-acf` folder in your theme, ideally a child theme so a theme update doesn't remove it.
2. Copy the template you want to change into it, keeping its path inside `templates/`. To change how images display, copy `wp-content/plugins/easeful-themes-for-acf/templates/fields/field-image.php` to `wp-content/themes/your-theme/easeful-themes-for-acf/fields/field-image.php`.
3. Edit your copy.

Your copy is used straight away for every field group and every theme. Easeful Themes for ACF looks in the child theme first, then the parent theme, then its own `templates/` folder.

Each template receives these variables:

- every template: `$renderer` (the renderer, see below), `$theme` (the resolved theme, with its `key`, `label` and `values`) and `$show_labels` (whether the theme shows labels);
- `group.php`: `$field_group` (the ACF field group array), `$fields_html` (the rendered fields) and `$post_id`;
- `field-wrap.php`: `$field` (the ACF field array), `$value_html` (the rendered value) and `$width` (`full`, `half`, `third` or `quarter`);
- `content-wrap.php`: `$content_html`, `$label` and `$width`;
- `fields/field-*.php`: `$field`, `$value` (what `get_field()` returns, in the field's own return format) and `$post_id`.

`$renderer->span_class( $width )` gives the column class for a width, and `$renderer->get_field_html( $sub_field, $sub_value, $post_id )` renders a sub field's value through its own template, which is how the group, repeater and flexible content templates work.

Escape everything you print. Markup that another template has already built — `$fields_html`, `$value_html`, `$content_html` — is printed through `wp_kses()` with the plugin's allowed tags, as the original templates do:

```php
<?php echo wp_kses( $value_html, EasefulThemesForACFKses::allowed_html() ); ?>
```

## How to Design a Field Type Without Its Own Template

Field types without a template of their own, including ones added by other plugins, all go through `fields/field-default.php`. Override that file and handle your type at the top, before the original code:

```php
<?php
if ( 'google_map' === $field['type'] && is_array( $value ) ) {
	printf(
		'<a href="%s" class="easeful-themes-for-acf__link">%s</a>',
		esc_url( 'https://www.google.com/maps/search/?api=1&query=' . rawurlencode( $value['address'] ) ),
		esc_html( $value['address'] )
	);
	return;
}

// ...the rest of the original field-default.php.
```

## How to Restyle the Output with CSS

Every class is prefixed `easeful-themes-for-acf`, and the stylesheet keeps its selectors simple, so your theme's CSS overrides it without needing `!important`. The main hooks:

- `.easeful-themes-for-acf` — the group's wrapper, along with `.easeful-themes-for-acf--{theme-key}` (for example `.easeful-themes-for-acf--minimal` or `.easeful-themes-for-acf--custom-42`) and a `data-easeful-themes-for-acf-group="group_…"` attribute with the field group's key;
- `.easeful-themes-for-acf__grid` — the twelve-column grid inside it;
- `.easeful-themes-for-acf__item` — one field's column, with `--full`, `--half`, `--third` or `--quarter`;
- `.easeful-themes-for-acf__card`, `.easeful-themes-for-acf__label` and `.easeful-themes-for-acf__value` — a field's card, its label and its value.

To style one field group only, scope your rules to its key:

```css
[data-easeful-themes-for-acf-group="group_652048389ef0b"] .easeful-themes-for-acf__label {
	font-style: italic;
}
```

The theme settings reach the stylesheet as CSS custom properties, set on the wrapper. Use them in your own CSS or templates so they keep following the theme: `--etfa-gap`, `--etfa-card-padding`, `--etfa-row-padding`, `--etfa-card-background`, `--etfa-border-width`, `--etfa-border-style`, `--etfa-border-color`, `--etfa-radius`, `--etfa-shadow`, `--etfa-font-size`, `--etfa-line-height`, `--etfa-label-size`, `--etfa-label-weight`, `--etfa-label-transform`, `--etfa-label-spacing`, `--etfa-text-color`, `--etfa-label-color`, `--etfa-muted-color`, `--etfa-link-color`, `--etfa-link-hover-color`, `--etfa-accent-color`, `--etfa-accent-background`, `--etfa-nested-background` and `--etfa-image-radius`.

```css
.easeful-themes-for-acf__value blockquote {
	border-left: 3px solid var(--etfa-accent-color);
	padding-left: var(--etfa-card-padding);
}
```

## How to Change the Output with Filters

`easeful_themes_for_acf_allowed_html` adds tags and attributes to what the templates may output. Rendered markup is escaped with the tags WordPress allows in post content, plus `<iframe>` for embeds, so a template that outputs a `<form>` or inline SVG needs them allowed here. It receives and returns a `wp_kses()` allowed-HTML array:

```php
add_filter( 'easeful_themes_for_acf_allowed_html', function ( $allowed ) {
	$allowed['form']  = array(
		'action' => true,
		'method' => true,
		'class'  => true,
	);
	$allowed['input'] = array(
		'type'        => true,
		'name'        => true,
		'value'       => true,
		'placeholder' => true,
	);
	return $allowed;
} );
```

`easeful_themes_for_acf_render_group_html` changes a whole rendered group before it's output. It receives the HTML, the ACF field group array, the post ID and the group's Easeful Themes for ACF settings. Its result is escaped again with the same allowed tags, so add any extra tag you need through `easeful_themes_for_acf_allowed_html`.

```php
add_filter( 'easeful_themes_for_acf_render_group_html', function ( $html, $field_group, $post_id, $settings ) {
	if ( 'group_652048389ef0b' !== $field_group['key'] ) {
		return $html;
	}
	return '<h2 class="product-specs-title">' . esc_html__( 'Specifications', 'my-theme' ) . '</h2>' . $html;
}, 10, 4 );
```

`easeful_themes_for_acf_template_candidates` changes where templates are looked up, for example to load them from a plugin instead of a theme. It receives the list of candidate file paths, highest priority first, and the requested template's path relative to `templates/`; the first file that exists is used:

```php
add_filter( 'easeful_themes_for_acf_template_candidates', function ( $candidates, $relative_path ) {
	array_unshift( $candidates, plugin_dir_path( __FILE__ ) . 'easeful-themes-for-acf/' . $relative_path );
	return $candidates;
}, 10, 2 );
```

To place a field group in a template file yourself, use `easeful_themes_for_acf_the_group( 'group_…' )`, or `easeful_themes_for_acf_get_group()` to get the HTML as a string. Both take an optional post ID and an array of options, such as `array( 'theme' => 'minimal' )`; the article on automatic display and the shortcode covers them in full.