Advanced Custom Fields: Widget

Note: This module has been adopted in ACF >= 5.0, want to know how to use it?

The ACF Widget is one of the must-have tools for developers who like working with Advanced Custom Fields. It allows users to create custom ACF field groups and use them easily in widgets. This tool is especially powerful when extending your own widgets to the ACF_Widget class. This enables you to develop your very own widgets. The user input is straightforward and simple, very much like using ACF.



In order to use this plugin, you need to install it onto your wordpress website.

  1. Download and install the Advanced Custom Fields plugin
  2. Download the ACF Widget zip archive from Github
  3. Upload the zip to your wp-content/plugins folder
  4. Navigate to your wp-admin, go to Plugins and activate the "Advanced Custom Fields: Widget" plugin.

Custom widgets with "ACF Widget"

If you are a developer and want to make your own widgets, you can extend the ACF_Widget class. This way, your clients can easily manage the widget in the admin and you can freely create the widget HTML output. Naturally, you will still be able to use Advanced Custom Fields in the HTML format.

class Spotlight_Widget extends ACF_Widget
	function __construct()
		$widget_options = array(
			"classname"     => "spotlight_widget",
			"description"   => "Widget with image, title and a link."
		parent::WP_Widget("Spotlight_Widget", "Spotlight", $widget_options);
		// This is the Group ID which will be preset in your custom widget
		$this->acf_group_id     = 110;
		// Want to show a title in the widget box, please fill in your title field key
		$this->title_field_key  = "title";
	function widget($args, $instance) 
 		// Variables
		$acf_key = "widget_" . $this->id_base . "_" . $this->number;
		// Widget HTML output
		echo "This is some widget HTML output";
$GLOBALS["acf_widget_types"][] = "spotlight_widget";

In the widget HTML output you can use Advanced Custom Fields, see example below.

the_field("field_name", $acf_key);


Create kick-ass widgets with ACF

Firstly, the wordpress theme needs to be informed about the custom widget. This can be done by putting the code below in your functions.php.

class Example_Widget extends WP_Widget
	function Example_Widget() 
		parent::WP_Widget(false, "Example Widget");
	function update($new_instance, $old_instance) 
		return $new_instance;  
	function form($instance)
		$title = esc_attr($instance["title"]);  
		echo "<br />";
	function widget($args, $instance) 
		$widget_id = "widget_" . $args["widget_id"];
		// I like to put the HTML output for the actual widget in a seperate file
		include(realpath(dirname(__FILE__)) . "/example_widget.php");

Now go to your Wordpress admin, hit the Custom Fields tab, and create a new Field Group. On the "Location" box, select "Widget" in the first select box. You will now see your widget, "Example Widget", in the third select box. Everything for the admin section is now set.

You are now able to create "Example Widgets" in the Wordpress admin section. This can be accomplished by clicking Appearance => Widgets. Drag your widget into the sidebar and you will see the fields you created using the ACF Field Group.

Your widget HTML output

Once everything is set up on the Admin section, you will see the Widget in the front end. As you may have noticed, you do not see anything until you create HTML output for the "Example Widget". Create a file called example_widget.php in the root folder of your theme.

The big question now is: How do we retrieve information from the Custom Fields plugin for this specific widget? Please have a close look at the code below and find out.

<div class="exampleWidget">
	<h3>This is our example widget</h3>
	<p>We can grab field values like this:</p>
	<?php the_field("example_field", $widget_id); ?>

Congratulations! You now know how to create awesome widgets for your Wordpress theme.