Search by

inc2734 / wp-customizer-framework

inc2734

A library for WordPress Customizer.

Package info

github.com/inc2734/wp-customizer-framework

pkg:composer/inc2734/wp-customizer-framework

Statistics

Installs: 9 101

Dependents: 1

Suggesters: 0

Stars: 20

Open Issues: 4

11.1.0 2026-11-13 05:31 UTC

README

CI Latest Stable Version License

A Framework of WordPress Customizer API.

Install

In your theme directory.

$ composer require inc2734/wp-customizer-framework

How to use

Initialize

require_once( get_theme_file_path( '/vendor/autoload.php' ) );

new \Inc2734\WP_Customizer_Framework\Bootstrap(
  'handle' => 'main style sheet handle',
);

Customizer

use Inc2734\WP_Customizer_Framework\Framework;

Framework::panel( 'panel-id', [
  'title' => 'panel-name',
] );

Framework::section( 'section-id', [
  'title' => 'section-name',
] );

Framework::control( 'type', 'control-id', [
  'label'   => 'Header Color',
  'default' => '#f00',
] );

$panel   = Framework::get_panel( 'panel-id' );
$section = Framework::get_section( 'section-id' );
$control = Framework::get_control( 'control-id' );

$control->join( $section )->join( $panel );
$control->partial( [
	'selector' => '.blogname',
] );

Lazy control UI arguments

Use the optional ui_args_callback to build labels, descriptions, choices, and other UI arguments only when they are needed:

Framework::control( 'select', 'layout', [
  'default' => 'wide',
  'ui_args_callback' => function () {
    return [
      'label' => __( 'Layout', 'my-theme' ),
      'choices' => [
        'wide' => __( 'Wide', 'my-theme' ),
        'narrow' => __( 'Narrow', 'my-theme' ),
      ],
    ];
  },
] );

The callback takes no arguments and returns an array. It runs once, when UI arguments are first read or the control is registered. Sanitizers that need choices also resolve it. get_control() still returns the original concrete control object; reading settings and defaults does not invoke the callback.

Supply all setting arguments, including default, type, capability, and sanitization callbacks, outside ui_args_callback. Setting arguments returned by the callback are ignored. Explicit UI arguments and values assigned with set_arg() or set_extend_arg() take precedence over deferred values, including assignments made before the callback runs. Existing controls without the callback retain their behavior.

Set styles

use Inc2734\WP_Customizer_Framework\Style;

add_action(
  'inc2734_wp_customizer_framework_load_styles',
  function() {
    $accent_color = get_theme_mod( 'accent-color' );

    Style::attach(
      'The handle of enqueued style',
      [
        [
          'selectors'  => [
            '.page-title',
            '.strong',
          ],
          'properties' => [
            "color: {$accent_color}",
            "border-bottom-color: {$accent_color}",
          ],
          'media_query' => '@media (min-width: 768px)', // Optional
        ],
      ]
    );
  }
);

Using placeholder

use Inc2734\WP_Customizer_Framework\Style;

add_action(
  'inc2734_wp_customizer_framework_load_styles',
  function() {
    /**
     * Extend "btn-base" placeholder
     *
     * Style::extend( 'btn-base', [ '.btn-a' ] );
     */
    include_once( get_theme_file_path( '/css/btn-a.php' ) );

    /**
     * Extend "btn-base" placeholder
     *
     * Style::extend( 'btn-base', [ '.btn-b' ] );
     */
    include_once( get_theme_file_path( '/css/btn-b.php' ) );

    /**
     * Extend "btn-base" placeholder
     *
     * Style::extend( 'btn-base', [ '.btn-c' ] );
     */
    include_once( get_theme_file_path( '/css/btn-c.php' ) );
  }
);

add_action(
  'inc2734_wp_customizer_framework_after_load_styles',
  function() {
    Style::placeholder(
      'btn-base',
      function( $selectors ) {
        $accent_color = get_theme_mod( 'accent-color' );

        Style::attach(
          'The handle of enqueued style',
          [
            [
              'selectors'  => $selectors,
              'properties' => [ "border-color: {$accent_color}" ],
            ],
          ]
        );
      }
    );
  }
);