README

WordPress setting field functions to output different type of fields.

Field Types Summary

Quick reference to all available field types:

• Text - Text input and textarea fields
• Dropdown - Select dropdown with custom options
• Switch (toggle) - Toggle/checkbox switch field
• Post type (dropdown) - Dropdown populated with posts of specified post types
• Taxonomy (dropdown) - Dropdown populated with taxonomy terms
• Pages (dropdown) - Dropdown populated with WordPress pages
• Button - Button field with action support
• Link (picker) - Link picker field using WordPress's built-in link modal

Field types

Text

Name: Kuuak\WordPressSettingFields\Fields::text

Arguments:

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::text',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for' => 'my-setting-id',
      'name'      => 'my-setting-name',
      'value'     => 'Value',
      'help'      => 'This is a text to help the user to understand the setting',
      'attrs'     => [
        'class' => 'large-text'
      ],
    ]
  );
} );

Dropdown

Name: Kuuak\WordPressSettingFields\Fields::dropdown

Arguments:

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::dropdown',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for' => 'my-setting-id',
      'name'      => 'my-setting-name',
      'selected'  => 'Value',
      'options'   => [
        [ 'value' => 'opt-1', 'title' => 'Option 1' ],
        [ 'value' => 'opt-2', 'title' => 'Option 2' ],
        [ 'value' => 'opt-3', 'title' => 'Option 3' ],
      ],
    ]
  );
} );

Switch (toggle)

Name: Kuuak\WordPressSettingFields\Fields::switch

Arguments:

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::switch',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for' => 'my-setting-id',
      'name'      => 'my-setting-name',
      'checked'   => true,
    ]
  );
} );

Post type (dropdown)

Name: Kuuak\WordPressSettingFields\Fields::post_type_dropdown

Arguments:

| name | type | mandatory | Description | | --------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------- | -------- | ----- | ----------------------------------------------------------------- | | query_args | array | false | WPQuery arguments. _See WP_Query::__construct() for accepted arguments | | name | string | true | Name of the dropdown | | selected | int | string | int[] | string[] | false | Optional. Value of the option that should be selected. Default 0. | | required | boolean | false | Optional. Whether the dropdown is required. Default false | | placeholder | string | false | Optional. | | show_option_all | string | false | Optional. Option all label for the Multiple version. Default All | | help | string | false | Optional. Help / description | | echo | boolean | false | Optional. Either to print the dropdown or not. Default true. | | nice_ui | boolean | false | Optional. Display as a nicer ui. Default true. | | attrs | array | false | Optional. Extra html atrributes for the select input. Attributes' name are the keys of the associative array. |

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::post_type_dropdown',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for'   => 'my-setting-id',
      'name'        => 'my-setting-name',
      'selected'    => 254,
      'query_args'  => [
        'post_type'   => ['my-custome-post-type'],
        'orderby'     => 'title',
        'order'       => 'ASC',
      ],
       'attrs'     => [
        'class' => 'large-text'
      ],
    ]
  );
} );

Taxonomy (dropdown)

Name: Kuuak\WordPressSettingFields\Fields::taxonomy_dropdown

Arguments:

See WP_Term_Query::__construct() for information on additional accepted arguments

| name | type | mandatory | Description | | --------------- | ------- | --------- | ------------------------------------------------------------------ | -------- | ----- | ----------------------------------------------------------------- | | name | string | true | Name of the dropdown | | taxonomy | string | true | Name of the taxonomy to | | selected | int | string | int[] | string[] | false | Optional. Value of the option that should be selected. Default 0. | | required | boolean | false | Optional. Whether the dropdown is required. Default false | | show_option_all | string | false | Optional. Option all label for the Multiple version. Default All | | hide_empty | string | false | Optional. Option all label | | help | string | false | Optional. Help / description | | echo | boolean | false | Optional. Either to print the dropdown or not. Default true. |

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::taxonomy_dropdown',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for'   => 'my-setting-id',
      'name'        => 'my-setting-name',
      'taxonomy'    => 'category',
      'selected'    => 254,
    ]
  );
} );

Pages (dropdown)

Name: Kuuak\WordPressSettingFields\Fields::pages_dropdown

Arguments:

See get_pages() for additional arguments

| name | type | mandatory | Description | | -------- | ------- | --------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | name | string | true | Name of the dropdown | | selected | int | string | false | Optional. Value of the option that should be selected. Default 0. | | required | boolean | false | Optional. Whether the dropdown is required. Default false | | help | string | false | Optional. Help / description. Default empty | | echo | boolean | false | Optional. Either to print the dropdown or not. Default true. |

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::pages_dropdown',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for'   => 'my-setting-id',
      'name'        => 'my-setting-name',
      'selected'    => 25,
    ]
  );
} );

Button

Name: Kuuak\WordPressSettingFields\Fields::button

Arguments:

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::button',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for' => 'my-setting-id',
      'name'      => 'my-setting-name',
      'label'     => 'Register now',
    ]
  );
} );

Link (picker)

Name: Kuuak\WordPressSettingFields\Fields::link

Renders a link field with WordPress's built-in link picker modal. Allows users to search for internal posts/pages or enter a custom URL. The field stores URL, link text, and target (for "open in new tab") values.

Arguments:

Example of usage

add_action( 'admin_init', function() {
  add_settings_field(
    'my-setting-id',
    __('My setting', 'my-setting-domain'),
    'Kuuak\WordPressSettingFields\Fields::link',
    'setting-page-id',
    'setting-section-id',
    [
      'label_for' => 'my-setting-id',
      'name'      => 'my-setting-name',
      'value'     => [
        'url'    => 'https://example.com',
        'text'   => 'Link Text',
        'target' => '_blank'
      ],
      'help'      => 'Pick a post/page or paste a custom URL.',
    ]
  );
} );

Note: When saving the form, the field will submit as an array with url, text, and target keys. The target value will be _blank if "open in new tab" is checked, or empty string otherwise.

Changelog

See CHANGELOG.md for a list of changes and version history.

Release Process

For release instructions, see the .cursor/rules/release-process.mdc file. This file contains a cursor rule that can be optionally used to guide the release process.