Guía completa: Cómo usar los hooks de Advanced Custom Fields (ACF)

Published on: noviembre 25, 2025Author: AlexComment: 0

Advanced Custom Fields (ACF) es un plugin de WordPress que facilita la creación y gestión de campos personalizados (textos, selects, repeaters, galerías, flexible content, etc.) mediante una interfaz visual. Permite almacenar datos estructurados asociados a posts, usuarios, taxonomías u opciones, y proporciona hooks (filters y actions) para interceptar su ciclo de vida: carga, render, validación, guardado y formateo.

Hooks principales

Filters

acf/load_field (+ name=/key=/type=)

Cuando: Antes de renderizar el campo en el admin.
Parámetros: array $field
Retorna: array $field
Usos: Modificar label, placeholder, choices, wrapper.

acf/prepare_field (+ name=/key=/type=)

Cuando: Antes de preparar el array final del campo.
Parámetros: array $field
Retorna: array $field
Usos: Modificar atributos finales, deshabilitar campo.

acf/load_value (+ name=/key=/type=)

Cuando: Al cargar el valor almacenado del campo.
Parámetros: $value, $post_id, array $field
Retorna: $value
Usos: Formatear el valor antes de mostrarlo.

acf/update_value (+ name=/key=/type=)

Cuando: Antes de guardar el valor del campo.
Parámetros: $value, $post_id, array $field
Retorna: $value
Usos: Validar o sanitizar valores.

acf/validate_value (+ name=/key=/type=)

Cuando: Al validar el valor de un campo.
Parámetros: $valid, $value, $field, $input
Retorna: $valid
Usos: Forzar requerimientos personalizados.

acf/format_value (+ name=/key=/type=)

Cuando: Al formatear el valor para ser usado en plantilla.
Parámetros: $value, $post_id, array $field
Retorna: $value
Usos: Ajustar presentación para frontend.

Actions

acf/save_post

Cuando: Después de guardar los campos ACF.
Parámetros: $post_id
Usos: Guardar info extra, sincronizar datos externos.

acf/delete_value

Cuando: Cuando se borra un valor ACF.
Parámetros: $post_id, $key
Usos: Limpieza de datos.

acf/render_field

Cuando: Al renderizar el HTML del campo.
Parámetros: array $field
Usos: Añadir HTML extra o atributos.

acf/render_field_settings

Cuando: Al renderizar configuración del campo en admin.
Parámetros: array $field
Usos: Crear opciones personalizadas.

acf/input/admin_enqueue_scripts

Cuando: Al cargar scripts CSS/JS en admin para ACF.
Usos: Encolar estilos o scripts personalizados.

Ejemplos prácticos

Caso 1:

Guardar campo ACF como meta del autor usando acf/save_post.

add_action( 'acf/save_post', 'saveAuthorMetaFromAcf' );

function saveAuthorMetaFromAcf( int $postID ): void {
  if ( isset( $_POST['acf'] ) && isset( $_POST['acf']['field_random_author_meta'] ) ) {
    $authorID = get_post_field( 'post_author', $postID );
    $fieldValue = sanitize_text_field( $_POST['acf']['field_random_author_meta'] );
    update_user_meta( $authorID, 'custom_author_meta', $fieldValue );
  }
}

Caso 2:

Modificar todos los campos select con acf/load_field/type=select

<?php
add_filter( 'acf/load_field/type=select', 'modifySelectFields' );

function modifySelectFields( $field ) {
  $field['choices']['new_option'] = 'Extra Option';
  return $field;
}

Caso 3:

Formatear valor numérico en frontend con acf/format_value

<?php
add_filter( 'acf/format_value/name=price_field', 'formatPriceValue', 10, 3 );

function formatPriceValue( $value, $postId, $field ) {
  return '$' . number_format( (float) $value, 2 );
}

Caso 4:

Validar campo obligatorio con acf/validate_value

<?php
add_filter( 'acf/validate_value/name=document_id', 'validateDocumentId', 10, 4 );

function validateDocumentId( $valid, $value, $field, $input ) {
  if ( empty( $value ) ) {
    $valid = 'Este campo es obligatorio.';
  }
  return $valid;
}

Caso 5:

Agregar clase CSS extra en acf/prepare_field

<?php
add_filter( 'acf/prepare_field/name=custom_title', 'addCustomClassToField' );

function addCustomClassToField( $field ) {
  $field['wrapper']['class'] .= ' highlight-title';
  return $field;
}

Caso 6:

Afectar valores antes de guardar con acf/update_value

<?php
add_filter( 'acf/update_value/name=website_url', 'sanitizeWebsiteBeforeSave', 10, 3 );

function sanitizeWebsiteBeforeSave( $value, $postId, $field ) {
  return esc_url_raw( $value );
}

Caso 7:

Hook para Flexible Content usando acf/load_field/type=flexible_content

<?php
add_filter( 'acf/load_field/type=flexible_content', 'customFlexibleContentLabel' );

function customFlexibleContentLabel( $field ) {
  $field['label'] = 'Custom Flexible Blocks';
  return $field;
}

Caso 8:

Repeater — manipular subcampos al guardar usando acf/save_post

<?php
add_action( 'acf/save_post', 'handleRepeaterOnSave' );

function handleRepeaterOnSave( $postId ) {
  // nombre del repeater: gallery_items
  if ( isset( $_POST['acf'] ) && isset( $_POST['acf']['field_gallery_items'] ) ) {
    $items = $_POST['acf']['field_gallery_items']; // array con filas
    // ejemplo: guardamos la cantidad de filas en un meta
    $count = is_array( $items ) ? count( $items ) : 0;
    update_post_meta( $postId, 'gallery_items_count', intval( $count ) );


    // recorrer filas y procesar subcampos (ej: image, caption)
    if ( is_array( $items ) ) {
      foreach ( $items as $index => $row ) {
        // $row normalmente contiene subcampos por key
        $caption = isset( $row['field_sub_caption'] ) ? sanitize_text_field( $row['field_sub_caption'] ) : '';
        // podemos guardar captions individuales en meta separados
        update_post_meta( $postId, "gallery_item_{$index}_caption", $caption );
      }
    }
  }
}

En esta guía viste los hooks principales de ACF, cómo distinguir filters de actions, y ejemplos prácticos para modificar la definición del campo, validar, sanitizar, formatear y reaccionar al guardado (incluyendo repeaters y flexible content). Usa estos snippets como base y adaptalos a los nameo keyreales de tus campos.