Get Craftor

Docs / Developers

Widget controls reference

Every control type get_content_controls() supports, with a render() example for each.

Every entry in the array get_content_controls() returns needs at minimum a name (the settings key) and a type. What ends up in $element->settings[name] — and therefore what render() reads — depends entirely on the type. The most commonly used ones:

text

php
array( 'name' => 'heading', 'type' => 'text', 'label' => 'Heading', 'default' => '' )
// render(): (string) $element->get_setting( 'heading', '' )

textarea

php
array( 'name' => 'message', 'type' => 'textarea', 'label' => 'Message', 'default' => '' )
// render(): same as text — a plain string, just edited in a multi-line box

select

php
array(
	'name'    => 'style',
	'type'    => 'select',
	'label'   => 'Style',
	'default' => 'solid',
	'options' => array( 'solid' => 'Solid', 'outline' => 'Outline' ),
)
// render(): (string) $element->get_setting( 'style', 'solid' ) — one of the option keys

switch (boolean toggle)

php
array( 'name' => 'showIcon', 'type' => 'switch', 'label' => 'Show Icon', 'default' => false )
// render(): ! empty( $element->get_setting( 'showIcon', false ) )

number

php
array( 'name' => 'columns', 'type' => 'number', 'label' => 'Columns', 'default' => 3 )
// render(): (int) $element->get_setting( 'columns', 3 )

color

php
array( 'name' => 'accentColor', 'type' => 'color', 'label' => 'Accent Color', 'default' => '#2451e0' )
// render(): (string) $element->get_setting( 'accentColor', '#2451e0' ) — a hex string

url (supports dynamic tags)

php
array( 'name' => 'link', 'type' => 'url', 'label' => 'Link', 'default' => '', 'dynamic' => true )
// render(): resolve dynamic tags before using the value as a real URL
$link = \Craftor\DynamicTags\DynamicTagsRegistry::instance()->resolve(
	(string) $element->get_setting( 'link', '' )
);

image

php
array(
	'name'    => 'photo',
	'type'    => 'image',
	'label'   => 'Photo',
	'default' => array( 'id' => 0, 'url' => '', 'alt' => '' ),
)
// render(): an { id, url, alt } array
$photo = (array) $element->get_setting( 'photo', array() );
$url   = (string) ( $photo['url'] ?? '' );
$alt   = (string) ( $photo['alt'] ?? '' );

icon

php
array( 'name' => 'icon', 'type' => 'icon', 'label' => 'Icon', 'default' => 'dashicons-star-filled' )
// render(): (string) $element->get_setting( 'icon', '' ) — either a Dashicon class name
// (e.g. 'dashicons-star-filled') or a direct URL to a custom-uploaded/pasted SVG icon —
// check for a leading 'dashicons-' before deciding how to render it:
$icon        = (string) $element->get_setting( 'icon', '' );
$is_dashicon = str_starts_with( $icon, 'dashicons-' );

checkboxGroup

php
array(
	'name'    => 'days',
	'type'    => 'checkboxGroup',
	'label'   => 'Open Days',
	'default' => array(),
	'options' => array( 'mon' => 'Monday', 'tue' => 'Tuesday', 'wed' => 'Wednesday' ),
)
// render(): a plain array of the selected option keys, e.g. ['mon', 'wed']
$days = (array) $element->get_setting( 'days', array() );

repeater (repeatable rows of sub-fields)

php
array(
	'name'    => 'items',
	'type'    => 'repeater',
	'label'   => 'Items',
	'default' => array( array( 'title' => 'First item' ) ),
	'fields'  => array(
		array( 'name' => 'title', 'type' => 'text', 'label' => 'Title', 'default' => '' ),
	),
)
// render(): an array of associative arrays, one per row, keyed by each sub-field's name
foreach ( (array) $element->get_setting( 'items', array() ) as $item ) {
	$title = (string) ( $item['title'] ?? '' );
}

A few more control types exist (wysiwyg, code, code-editor, expression, mediaUrl, conditionGroup, and several Craftor-feature-specific selects) — grep app/editor/components/controls/ContentControls.tsx in Craftor's own source for the complete, current list if you need one of the less common ones.

Two keys work on any control type, regardless of the ones above:

  • default — used both as the initial value and by get_default_settings() (which every widget inherits) to pre-fill settings for a freshly-inserted element.
  • description — a short helper line shown under the control in the Content panel.
PreviousCreating a custom widgetNext Creating a custom automation action