acf-pro-options-pages
Builds and reviews ACF PRO options pages and their global value storage. Covers acf_add_options_page registration, capabilities, menu and location rules, default and custom post_id prefixes in wp_opti
SKILL.mdacf/acf-pro-options-pages/SKILL.md
GitHubACF 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.
Read and render from the same target
$storage = 'option_acme_brand';
$phone = get_field( 'acme_support_phone', $storage );
if ( is_string( $phone ) && '' !== $phone ) {
printf(
'<a href="%s">%s</a>',
esc_url( 'tel:' . preg_replace( '/[^0-9+]/', '', $phone ) ),
esc_html( $phone )
);
}
The common 'option' and 'options' aliases target default options storage.
They do not target a custom post_id. Centralize a custom storage identifier in
one constant or method and reuse it for field definitions, reads, writes, tests,
and migrations.
Prevent page collisions
Two pages using default storage and the same field name read and overwrite the same option. Choose one of these models:
- globally unique field names across all default options pages;
- a distinct custom
post_idper independent page/tenant/brand; - intentionally shared fields, documented as shared state.
Changing post_id later is a data migration. Copy both the raw value and its
reference by reading through the old ACF target and writing through
update_field( $field_key, $value, $new_target ); then verify and remove the old
options according to the rollback plan.
Control autoload and size
ACF PRO 6.8.10 defaults an options page's autoload setting to false. Enabling
it can improve access to a small set of values used on nearly every request, but
it also adds those option rows to WordPress's autoloaded option set.
- Keep large Repeaters, Flexible Content, galleries, and rarely used settings non-autoloaded.
- Measure total autoloaded option size before and after enabling it.
- Avoid storing caches, logs, queues, or frequently changing operational state in an ACF options page.
- Do not assume ACF's formatted-value cache replaces WordPress option/object cache design.
Free/PRO degradation
acf_add_options_page() and the Options Pages UI require ACF PRO. A plugin
whose core behavior depends on the page should show one clear administrator
notice and disable only that feature when the function is absent. Do not create
a lookalike page that writes incompatible option names under ACF Free.
Verification
- Log in with an allowed administrator and a role that must be denied.
- Save a scalar, an empty value, and each complex value used by the page.
- Inspect the expected prefixed option and underscore reference.
- Render on a frontend request without an admin global screen.
- Confirm a second options page cannot collide unintentionally.
- Measure autoload growth and object-cache behavior where relevant.
- Exercise import/CLI writes with the exact custom storage target.
Cross-references
acf-field-group-developmentfor options-page location rules and schema ownership.acf-value-storage-frontendfor raw/formatted values and safe output.acf-pro-complex-fieldswhen global settings contain Repeaters or Flexible Content.
References
- Official Options Page documentation.
- Official guide to values from an options page.
- Official ACF PRO feature overview.
- Verified ACF PRO 6.8.10 source paths:
pro/options-page.phppro/admin/admin-options-page.phppro/locations/class-acf-location-options-page.phppro/acf-ui-options-page-functions.php
- Verified shared source paths:
includes/acf-meta-functions.phpsrc/Meta/Option.php