ACF Button Link Component — Reusable PHP Renderer

Raw ACF Link output works. The problem is repetition and inconsistency. An ACF Link field returns an array — [ 'title' => '...', 'url' => '...', 'target' => '...' ] — and every template that renders a button repeats the same three lines: check the array is populated, print the href, print the target, print the title. Forgetting esc_url() on one template creates an XSS vector. Changing the primary button class requires a find-and-replace across every template file. One typo in a target attribute can break analytics tracking.

theme_btn() solves null-safety and escaping in one call. The function checks that both url and title are non-empty — an ACF Link field with only a title but no URL is invalid, and vice versa. If either is missing, the function returns an empty string. The output runs through three WordPress escaping functions: esc_url() strips invalid protocols and special characters from the URL, esc_html() prevents HTML injection in the label text, and esc_attr() sanitises the target value. These three calls make the button safe regardless of what the content editor enters.

The variant system decouples presentation from data. The ACF Link field stores the content — URL, label, target. The variant tells your CSS how to style it — filled background, bordered, or text-only. By limiting variants to a whitelist (primary | secondary | ghost | outline), you prevent a CSS class from breaking because someone typed "prymary". The in_array() check with a strict comparison ensures only valid modifiers reach the output.

The variant maps directly to a BEM modifier class (btn--primary), which means your CSS uses predictable selectors. You can style .btn--primary, .btn--secondary, .btn--ghost, and .btn--outline in one SCSS file and every button in the theme follows those rules.

The icon system keeps SVG markup in one place — the icon partial files in your theme — and passes them as raw strings to the button component. The icon_position parameter (before | after) controls whether the icon appears to the left or right of the label. The function wraps icons in <span class="btn__icon btn__icon--{before|after}" aria-hidden="true"> so screen readers ignore them (the button label already describes the action) and your CSS can target icon spacing with .btn__icon--after { margin-left: 0.5rem; }.

The icon is a raw SVG string — not a file path. This means you control the exact markup and can pass currentColor-styled SVGs that inherit the button’s text colour on hover. This is deliberate: icon font libraries add CSS weight and framework dependency. Inline SVGs styled with stroke="currentColor" need zero additional CSS.

The production component combines all parameters into one signature. wp_parse_args() merges the caller’s array with defaults so optional arguments don’t need to be passed every time. The $target_attr variable adds rel="noopener" when the link opens in a new tab — this is a security best practice that prevents the opened page from accessing window.opener. The $class variable concatenates the base class, the variant modifier, and any additional classes from the caller. The icon and label are ordered based on icon_position using two variables ($parts_before, $parts_after) that hold whichever component goes first.

Create inc/theme-btn.php with the Step 5 code. In functions.php, add the require statement at the top of the file:

require_once get_template_directory() . '/inc/theme-btn.php';

This makes theme_btn() available in every template file.

Create your ACF Link fields. In your field group, add a field with Field Type → Link. Set the Return Format to Link Array — this is the format theme_btn() expects. Name your fields consistently: hero_cta, section_link, footer_button. The name becomes the first argument to theme_btn().

Create icon partials. Each SVG lives in a small PHP file under template-parts/icons/. For example, template-parts/icons/arrow-right.php:

<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">n    <path d="M6 3l5 5-5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>n</svg>

Capture the SVG output in your template using output buffering or a helper, then pass it to theme_btn():

// In your template:nob_start();nget_template_part( 'template-parts/icons/arrow-right' );n$arrow_icon = ob_get_clean();nnecho theme_btn( 'hero_cta', [n    'variant'       => 'primary',n    'icon'          => $arrow_icon,n    'icon_position' => 'after',n] );

Replace your raw button markup. In hero.php, change:

// Before — 8 lines of manual HTML.n$cta = get_field( 'hero_button' );nif ( $cta ):n    ?>n    <a href="<?php echo esc_url( $cta['url'] ); ?>"n       target="<?php echo esc_attr( $cta['target'] ?: '_self' ); ?>"n       class="btn btn--primary"><?php echo esc_html( $cta['title'] ); ?></a>n    <?phpnendif;nn// After — 1 line.necho theme_btn( 'hero_button', [ 'variant' => 'primary' ] );

Repeat for every template that renders an ACF Link field. Your templates shrink and every button shares the same escaping, validation, and markup.

Add a size variant. If your design system has small, regular, and large buttons, add a size parameter that appends a second BEM modifier:

$valid_sizes = [ 'sm', 'md', 'lg' ];n$size = in_array( $args['size'], $valid_sizes, true ) ? $args['size'] : 'md';nn// In the sprintf, change the class line to:n$class = trim( sprintf( 'btn btn--%s btn--%s %s', $variant, $size, esc_attr( $args['class'] ) ) );

The same whitelist pattern keeps invalid values from leaking into your output. Your CSS targets .btn--sm, .btn--md, and .btn--lg.

Add a wrapper element for alignment. If your buttons need to be centered or aligned to the right in a flex container, add a wrapper parameter that optionally wraps the anchor tag:

if ( $args['wrapper'] ) {n    return sprintf( '<div class="btn-wrapper btn-wrapper--%s">%s</div>',n        esc_attr( $args['wrapper_align'] ?? 'left' ),n        theme_btn( $field, array_merge( $args, [ 'wrapper' => false ] ) )n    );n}

This keeps the button component focused on rendering the anchor tag while the wrapper handles layout concerns.

Add a theme_btn_manual() helper for non-ACF links. Not every button comes from an ACF field — sometimes you have a hardcoded URL or a WordPress permalink:

function theme_btn_manual( string $url, string $label, array $args = [] ): string {n    $args = wp_parse_args( $args, [n        'variant'       => 'primary',n        'icon'          => '',n        'icon_position' => 'after',n        'class'         => '',n        'target'        => '_self',n    ] );nn    $link = [n        'url'    => $url,n        'title'  => $label,n        'target' => $args['target'],n    ];nn    // Temporarily override the ACF field lookup —n    // the rest of theme_btn stays the same.n    $original = get_field( '_placeholder_' );n    add_filter( 'acf/load_value', function( $value ) use ( $link ) {n        static $called = 0;n        return $called++ ? $value : $link;n    } );n    $output = theme_btn( '_placeholder_', $args );n    remove_all_filters( 'acf/load_value' );n    return $output;n}

This approach reuses all the escaping, variant logic, and icon rendering from theme_btn() without duplicating code. Alternatively, refactor the internal rendering into a shared private helper.

Create a button group component for side-by-side buttons. Hero sections often have two buttons — a primary CTA and a secondary link. Write a theme_btn_group() that accepts two ACF Link field names and renders both inside a flex wrapper:

function theme_btn_group( array $buttons, array $args = [] ): string {n    $args = wp_parse_args( $args, [n        'gap'    => 'md',n        'align'  => 'left',n        'class'  => '',n    ] );nn    $html = '';n    foreach ( $buttons as $btn ) {n        $html .= theme_btn(n            $btn['field'] ?? '',n            $btn['args'] ?? []n        );n    }nn    if ( ! $html ) return '';nn    return sprintf(n        '<div class="btn-group btn-group--%s btn-group--%s %s">%s</div>',n        esc_attr( $args['gap'] ), esc_attr( $args['align'] ),n        esc_attr( $args['class'] ), $htmln    );n}nn// Usage:necho theme_btn_group( [n    [ 'field' => 'primary_cta',  'args' => [ 'variant' => 'primary' ] ],n    [ 'field' => 'secondary_cta', 'args' => [ 'variant' => 'outline' ] ],n], [ 'gap' => 'md', 'align' => 'center' ] );