Home » Documentation

 This plugin is only compatible with ACF v5 or later.

Creating New Widgets

Navigate to Appearance > Add New Widgets and then click Add Widget button next to the title of the page. Give your widget a title and an optional description. After publishing, the widget will be available like any other widget.

Assigning Fields to a Widget

In the ACF admin area, create a new Field Group. Add any of the fields that you want for your new widget. Then under the Location meta box, set it equal to Widget is equal to Your Custom Widget. The process is identical for 3rd Party Widgets.

Creating & Using Templates

To show your widgets custom fields, you will first need to create a template file and include it in your theme. You can find the required name for the widget in the admin area of your website. Navigate to Appearance > Add New Widgets and the name of the template is shown in the second column across from the title of it’s respective widget. The normal format of templates is equal to widget-slug.php though you can optionally use widget-id.php. Note, all widget templates are prefixed with widget- and end with a .php extension. For 3rd Party Widgets, only the widget-slug.php template is searched for. You can find the required template name for 3rd Party Widgets by enabling Template Debugging on the Settings > ACFW Options page. For WordPress widgets, there are pre-named templates bundled with the plugin in the templates folder in the plugin root.

Inside of your templates you can use any combination of tags available to normal PHP files. To retrieve values from your custom fields, you can use the normal ACF API. One example would be
<?php the_field('CUSTOM_FIELD_NAME', $acfw); ?>. Note you must pass in the predefined $acfw variable as the second parameter to any ACF function used within widget templates. This tell’s ACF to look for the fields associated with that particular instance of your widget. Since there is no limitation to the amount of widgets that can be shown at any time, this differentiates the widgets from other instances of the same type.

Where to Display Custom Fields

You will notice that when assigning widgets to a sidebar, standard WordPress Widgets and 3rd Party Widgets have an additional field added by the plugin. For WordPress widgets, you can display your custom fields above the widget, below the title, or below the widget. Since all third party widgets do not include a title field, that option has been removed.

Got more questions?

Visit the Support Forums