.com

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 echo wp_kses( $value_html, \EasefulThemesForACF\Kses::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
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:

[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.

.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:

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.

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:

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.