Adding a custom field type

Updated 15 September 2026

What is it?

Since v2.2 you can show your own Gravity Forms field type in the live summary and its mergetags. It takes a PHP filter, a small JavaScript class and, if you need it, a filter for the mergetag output. This page walks through a complete example: a “Star rating” field with a “Maximum stars” setting that shows up in the summary as “★★★☆☆ 3 / 5”.

1. Tell the plugin about your field type

Add the type of your field to the supported field types. The field can then be selected in the Visible fields selector and gets the Live Summary tab in the form editor (summary label, prefix, suffix and CSS class).

add_filter( 'gotrls_supported_field_types', function ( $types ) {
	$types[] = 'gotrls_star_rating'; // The $type of your GF_Field class.
	return $types;
} );

2. Pass your field settings to the page (optional)

The summary only receives a fixed set of field properties. Anything extra that your JavaScript class needs, such as the maximum number of stars, is added with the gotrls_field_data filter. It is available in the class as this.fieldData.

add_filter( 'gotrls_field_data', function ( $data, $field ) {
	if ( 'gotrls_star_rating' === $field->type ) {
		$data['maxStars'] = (int) $field->maxStars;
	}
	return $data;
}, 10, 2 );

3. Load a script after the plugin script

The plugin loads its script with the handle gotrls-frontend-scripts on forms that have a summary. Enqueue your own script with that handle as a dependency, so it is printed after the plugin script and only on those pages.

add_action( 'gform_enqueue_scripts', function ( $form ) {
	if ( ! wp_script_is( 'gotrls-frontend-scripts', 'enqueued' ) ) {
		return; // No summary on this form.
	}
	wp_enqueue_script( 'my-star-rating-summary', plugins_url( 'star-rating-summary.js', __FILE__ ), array( 'gotrls-frontend-scripts' ), '1.0', true );
}, 20 );

4. Register a JavaScript class for the type

Your class extends gotrLiveSummaries.Field. Only getValue() is required: return the value, or false to leave the field out of the summary. Without a render() method you get the standard line: the label on the left, the value on the right, with the prefix and suffix from the Live Summary tab. Add render() when you want your own markup, like the stars below.

( function () {
	const liveSummary = window.gotrLiveSummaries;

	if ( ! liveSummary || 'function' !== typeof liveSummary.registerFieldType ) {
		return; // Live Summary is not loaded, or older than 2.2.0.
	}

	class StarRating extends liveSummary.Field {
		// The number of stars chosen, or false when none is chosen (the line is then hidden).
		getValue() {
			const checked = document.querySelector( `#field_${ this.formId }_${ this.fieldId } input[type="radio"]:checked` );
			return checked ? parseInt( checked.value, 10 ) : false;
		}

		// Optional: your own markup for the line.
		render() {
			const stars = this.getValue();
			const max   = parseInt( this.fieldData.maxStars, 10 ) || 5; // From the gotrls_field_data filter.
			const icons = '★'.repeat( stars ) + '☆'.repeat( Math.max( 0, max - stars ) );
			const text  = liveSummary.escapeHtml( `${ stars } / ${ max }` );

			return `
				<div class="gotrgf_line_part_left">${ this.getLabel() }</div>
				<div class="gotrgf_line_part_right">${ this.maybeApplyValueSuffixPrefix( `${ icons } ${ text }` ) }</div>
			`;
		}
	}

	liveSummary.registerFieldType( 'gotrls_star_rating', StarRating );
} )();

What you can use in the class:

• this.formId, this.fieldId, this.fieldData
  The form, the field and the field data from PHP.
• this.getLabel()
  The label of the field, or the summary label from the Live Summary tab.
• this.maybeApplyValueSuffixPrefix( value )
  Wraps the value in the prefix and suffix from the Live Summary tab.
• gotrLiveSummaries.escapeHtml( value )
  Escapes text that comes from the visitor before you put it in your markup.
• CSS classes
  gotrgf_line_part_left and gotrgf_line_part_right for the two halves of a line, gotrgf_unordered_list for a list of values.

5. Keep the summary up to date

The summary refreshes by itself when Gravity Forms reports a change of an input (gform_input_change), after conditional logic and after a page change. The stars are radio buttons, so nothing more is needed. A widget that changes its value some other way, such as a canvas or a custom picker, calls the refresh itself:

gotrLiveSummaries.debouncedRefresh( formId );

6. The mergetags

The {live_summary} mergetag shows what the get_value_entry_detail() method of your GF_Field class returns, so a proper field class needs nothing extra. To change the value for the summary only, use the gotrls_mergetag_field_value filter. Return an empty string to leave the field out.

add_filter( 'gotrls_mergetag_field_value', function ( $value, $field, $entry, $format ) {
	if ( 'gotrls_star_rating' !== $field->type || '' === $value || 'html' !== $format ) {
		return $value; // Plain "3 / 5" in text emails.
	}
	$stars = (int) rgar( $entry, (string) $field->id );
	$max   = (int) $field->maxStars;
	return esc_html( str_repeat( '★', $stars ) . str_repeat( '☆', max( 0, $max - $stars ) ) ) . ' ' . $value;
}, 10, 4 );

The complete example

The Star rating field, its editor setting and the code above are available as a small must-use plugin that you can drop in your wp-content/mu-plugins folder to try it out.

Download: gotrls-star-rating-example.zip

Developer hooks

gotrls_supported_field_types, gotrls_field_data, gotrls_mergetag_field_value, gotrLiveSummaries.registerFieldType