Adding custom javascript to fields

Overview

This article will cover how to add custom JS to interact with and modify ACF fields and settings. Similar to the many WordPress actions and filters available in PHP, ACF adopts a similar model for it’s Javascript.

Getting Started

There are two methods to add custom javascript to the WordPress dashboard; include a script file or append an inline script. It is recommended that you include a JS file if you intend to write lots of functionality.

Include

To include a JS file within the dashboard, you can make use of the wp_enqueue_script function like so.

functions.php

function my_admin_enqueue_scripts() {

	wp_enqueue_script( 'my-admin-js', get_template_directory_uri() . '/js/example.js', array(), '1.0.0', true );

}

add_action('admin_enqueue_scripts', 'my_admin_enqueue_scripts');

Inline

To append inline JS within the dashboard, you can make use of the acf/input/admin_footer action. This action is run in the footer of any admin page where ACF fields may exist.

functions.php

function my_acf_input_admin_footer() {
	
?>
<script type="text/javascript">
(function($) {
	
	// JS here
	
})(jQuery);	
</script>
<?php
		
}

add_action('acf/input/admin_footer', 'my_acf_input_admin_footer');

Actions

Below is a list of all available JS actions. Please note that there are multiple ways to hook into an action (global, field). Hooking into an action is made possible by a function called add_action on the acf object. If you are using the reay action, it is a good idea to also hook into the append action with the same functionality.

Ready

Called when the document is ready once the page has initially loaded.

acf.add_action('ready', function( $el ){
	
	// $el will be equivalent to $('body')
	
	
	// find a specific field
	var $field = $('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions ready_field and ready_field/type={$field_type}.

Append

Called when new HTML is appended to the page. This occurs when adding a new repeater row, adding a new flexible content layout and when new field groups are loaded via AJAX. If you are using the append action, it is a good idea to also hook into this action with the same functionality.

acf.add_action('append', function( $el ){
	
	// $el will be equivalent to the new element being appended $('tr.row')
	
	
	// find a specific field
	var $field = $el.find('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions append_field and append_field/type={$field_type}.

Load

Called when the window has loaded all assets. This action is desired over ‘ready’ when the width and height if an image is needed for logic.

acf.add_action('load', function( $el ){
	
	// $el will be equivalent to $('body')
	
	
	// find a specific field
	var $field = $el.find('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions load_field and load_field/type={$field_type}.

Remove

Called when HTML is removed from the page. This occurs when removing a repeater row or removing a flexible content layout.

acf.add_action('remove', function( $el ){
	
	// $el will be equivalent to the new element being removed $('tr.row')
	
	
	// find a specific field
	var $field = $el.find('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions remove_field and remove_field/type={$field_type}.

sortstart

Called when HTML has begun to move around the page via drag/drop. This occurs when reordering a repeater row or reordering a flexible content layout.

acf.add_action('sortstart', function( $el ){
	
	// $el will be equivalent to the new element being moved $('tr.row')
	
	
	// find a specific field
	var $field = $el.find('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions sortstart_field and sortstart_field/type={$field_type}.

sortstop

Called when HTML has finished being moved around the page via drag/drop. This occurs when reordering a repeater row or reordering a flexible content layout.

acf.add_action('sortstop', function( $el ){
	
	// $el will be equivalent to the new element being moved $('tr.row')
	
	
	// find a specific field
	var $field = $el.find('#my-wrapper-id');
	
	
	// do something to $field
	
});

This action also fires on each field via the actions sortstop_field and sortstop_field/type={$field_type}.

hide_field

Called when a field has been hidden via either a tab or by conditional logic.

acf.add_action('hide_field', function( $field, context ){
	
	// context is a string of either 'tab' or 'conditional_logic'
	
	// do something to $field
	
});

This action also fires on a field specific basis hide_field/type={$field_type}.

show_field

Called when a field has been shown via either a tab or by conditional logic.

acf.add_action('show_field', function( $field, context ){
	
	// context is a string of either 'tab' or 'conditional_logic'
	
	// do something to $field
	
});

This action also fires on a field specific basis show_field/type={$field_type}.

Filters

validation_complete

This filter allows the validation JSON response to be customized. Called after AJAX validation is complete but before errors are shown or the form is submitted.

acf.add_filter('validation_complete', function( json, $form ){
	
	// if errors?
	if( json.errors ) {
		
		
		
	}
	
	
	// return
	return json;
			
});

wysiwyg_tinymce_settings

This filter allows the tinyMCE settings to be customized for each WYSIWYG field. Called before the tinyMCE instance is created.

acf.add_filter('wysiwyg_tinymce_settings', function( mceInit, id ){
	
	// do something to mceInit
	
	
	// return
	return mceInit;
			
});

wysiwyg_quicktags_settings

This filter allows the quicktags settings to be customized for each WYSIWYG field. Called before the text instance is created.

acf.add_filter('wysiwyg_quicktags_settings', function( qtInit, id ){
	
	// do something to qtInit
	
	
	// return
	return qtInit;
			
});

date_picker_args

This filter allows the date picker settings to be customized for each date picker field. Called before the date picker instance is created. A full list of settings can be found here: https://api.jqueryui.com/datepicker/

acf.add_filter('date_picker_args', function( args, $field ){
	
	// do something to args
	
	
	// return
	return args;
			
});

date_time_picker_args

This filter allows the date time picker settings to be customized for each date time picker field. Called before the date time picker instance is created. A full list of settings can be found here: http://trentrichardson.com/examples/timepicker/

acf.add_filter('date_time_picker_args', function( args, $field ){
	
	// do something to args
	
	
	// return
	return args;
			
});

time_picker_args

This filter allows the time picker settings to be customized for each time picker field. Called before the time picker instance is created. A full list of settings can be found here: http://trentrichardson.com/examples/timepicker/

acf.add_filter('time_picker_args', function( args, $field ){
	
	// do something to args
	
	
	// return
	return args;
			
});

google_map_args

This filter allows the google maps settings to be customized for each googe maps field. Called before the map instance is created.

acf.add_filter('google_map_args', function( args, $field ){
	
	// do something to args
	
	
	// return
	return args;
			
});

select2_args

This filter allows the select2 settings to be customized for each select field. Called before the select2 instance is created.

acf.add_filter('select2_args', function( args, $select, settings ){
	
	// do something to args
	
	
	// return
	return args;
			
});

color_picker_args

This filter allows the color picker (wpColorPicker) settings to be customized for each color picker field. This filter is called before the wpColorPicker instance is created. Added in v 5.3.6

acf.add_filter('color_picker_args', function( args, $field ){
	
	// do something to args
	args.palettes = ['#5ee8bf', '#2f353e', '#f55e4f']
	
	
	// return
	return args;
			
});