acf-pro-options-pages

ACF PRO options pages

Options Pages are an ACF PRO feature. They provide an admin screen and field location; their values live in wp_options, not in a special ACF table. Default options pages share the same options storage target, so page separation in the menu does not isolate duplicate field names.

Register a page with explicit policy

add_action( 'acf/init', static function (): void {
    if ( ! function_exists( 'acf_add_options_page' ) ) {
        return;
    }

    acf_add_options_page( array(
        'page_title'    => __( 'Brand settings', 'acme-brand' ),
        'menu_title'    => __( 'Brand settings', 'acme-brand' ),
        'menu_slug'     => 'acme-brand-settings',
        'capability'    => 'manage_options',
        'redirect'      => false,
        'post_id'       => 'option_acme_brand',
        'autoload'      => false,
        'update_button' => __( 'Save brand settings', 'acme-brand' ),
    ) );
} );

Then attach a field group with an Options Page location rule whose value matches the menu slug. Keep registration and field definitions in the same owning plugin so the page cannot exist without its schema.

edit_posts is the ACF default capability. That is often too broad for global configuration. Choose a capability from the feature's authorization model and recheck it on any custom save, REST, AJAX, or CLI path.

Understand option names

With the default post_id of options, a field named support_phone produces:

options_support_phone   = <raw value>
_options_support_phone  = field_acme_support_phone

With post_id => 'option_acme_brand', the same field produces:

option_acme_brand_support_phone   = <raw value>
_option_acme_brand_support_phone  = field_acme_support_phone

The underscore option is ACF's field-key reference. Keep it aligned with the value option. Do not call get_option( 'support_phone' ) and assume it is the ACF value; use get_field() with the same storage target or intentionally address the fully prefixed raw option.