ACFリピーターで最初のサブフィールドだけ表示する方法【break／reset_rows】

公開日: 2021.07.23
最終更新日: 2026.07.17

WordPressでコーポレートサイトを制作するとき、まず入れておきたいプラグインがAdvanced Custom Fields（ACF）です。そのACFの繰り返しフィールド（Repeater Field）で画像ギャラリーを組んだとき、「一覧では最初の1枚だけをサムネイルとして表示したい」という場面があります。

結論から言うと、繰り返しフィールドのループ内で最初の値を取得したあと、breakでループを中断するだけで、最初のサブフィールドだけを表示できます。この記事では、その具体的なコードと、同じフィールドをあとで全件表示したい場合の対処（reset_rows()）まで解説します。

1 最初のサブフィールドだけ表示する
2 コードのポイント
3 同じフィールドをあとで全件表示したい場合
4 ループを使わずに最初の1件を取得する
5 まとめ

最初のサブフィールドだけ表示する

やり方はシンプルで、ループを1周回したところでbreakを使い、繰り返しを止めます。

<?php if (have_rows('repeater')) : ?>
    <div>
        <?php while (have_rows('repeater')) : the_row();
            $subField = get_sub_field('subField');
        ?>
            <img src="<?php echo $subField['url']; ?>" alt="<?php echo $subField['alt']; ?>" />
            <?php break; // 最初の1件を出力したらループを中断 ?>
        <?php endwhile; ?>
    </div>
<?php endif; ?>

これで、繰り返しフィールドに何件登録されていても、表示されるのは最初の1件だけになります。

コードのポイント

ACFの繰り返しフィールドは、have_rows()で行の有無を確認し、whileとthe_row()で1行ずつ処理を進めるのが基本形です。各行の値はget_sub_field()で取得します。

ここでの肝は、breakを置く位置です。最初の行の画像を出力したあとにbreakを実行することで、2件目以降に進む前にループを抜けます。結果として、1件目だけが表示されるというわけです。the_row()は「次の行に進む」関数で、これを呼ぶことでその行のサブフィールドがget_sub_field()で取得できるようになります。この3つはセットで覚えておくと、繰り返しフィールドの扱いに迷いません。

実務では、実績一覧やスタッフ紹介などを繰り返しフィールドで管理し、トップページや一覧では代表画像として1枚目だけを出す、という使い方をよくします。同じデータを、詳細ページでは全件、一覧では1件目だけ、と出し分けられるのがACFの便利なところです。

同じフィールドをあとで全件表示したい場合

注意したいのは、同じ繰り返しフィールドを同じページ内でもう一度ループしたいケースです。上記のようにbreakで中断したままだと、次にループを回したとき2周目の途中から始まってしまうことがあります。ACFが内部で「今どの行まで処理したか」を覚えているためです。

ループを最初に戻して再開したい場合は、reset_rows()を使ってループをリセットします。

<?php // 最初のループ（1件目だけ表示） ?>
<?php if (have_rows('repeater')) : ?>
    <div>
        <?php while (have_rows('repeater')) : the_row();
            $subField = get_sub_field('subField');
        ?>
            <img src="<?php echo $subField['url']; ?>" alt="<?php echo $subField['alt']; ?>" />
            <?php break; ?>
        <?php endwhile; ?>
        <?php reset_rows(); // ループをリセット ?>
    </div>
<?php endif; ?>

<?php // ループを再開（全件表示） ?>
<?php if (have_rows('repeater')) : ?>
    <div>
        <?php while (have_rows('repeater')) : the_row();
            $subField = get_sub_field('subField');
        ?>
            <img src="<?php echo $subField['url']; ?>" alt="<?php echo $subField['alt']; ?>" />
        <?php endwhile; ?>
    </div>
<?php endif; ?>

1つ目のループでreset_rows()を呼んでおくことで、2つ目のループが正しく1件目から始まります。「サムネイルとして1枚目を見せてから、下に全画像を並べる」といったレイアウトも、これで無理なく実装できます。

ループを使わずに最初の1件を取得する

実は、繰り返しフィールドを配列として受け取り、最初の要素だけを取り出す書き方もあります。get_field()は繰り返しフィールド全体を配列で返すため、[0]で先頭の行に直接アクセスできます。

<?php
$rows = get_field('repeater');
if ($rows) {
    $first = $rows[0]['subField'];
    echo '<img src="' . esc_url($first['url']) . '" alt="' . esc_attr($first['alt']) . '">';
}
?>

ループを回さないぶんコードがすっきりし、reset_rows()を気にする必要もありません。一方で、行ごとに条件分岐や加工を挟みたい場合はwhileループのほうが柔軟です。「1件目を取り出すだけ」なら配列アクセス、「途中で処理を分けたい」ならループ、と使い分けるとよいでしょう。

なお、URLなどを出力するときはesc_url()やesc_attr()でエスケープしておくと、より安全に扱えます。ユーザーが入力した値をそのまま出力しない、という基本を押さえておくと安心です。