When building templates in Craft CMS, you will frequently find yourself iterating through collections of data—whether they are entries, assets, or Matrix blocks. Often, the first item in that collection requires special treatment. Perhaps the first image in a gallery needs a specific CSS class for a hero layout, or the latest blog post in a list needs a different HTML structure to stand out.

Understanding how to target the first item efficiently is a fundamental skill for any Craft CMS developer. In this guide, we will explore the different ways to isolate the first element of a collection, depending on whether you are inside a loop or trying to fetch a single item from a query.

Using the loop.first Variable Inside a Loop

If you are already iterating through a set of items using a for loop, Twig provides a very convenient way to identify the first iteration. The loop variable is an object available inside any for loop that contains several helpful properties.

To target the first item, you use loop.first, which returns a boolean true only during the first pass of the loop.

{% for image in entry.myAssetsField.all() %}
    <div class="image-wrapper {{ loop.first ? 'is-featured' : '' }}">
        <img src="{{ image.url }}" alt="{{ image.title }}">
    </div>

    {% if loop.first %}
        <p>This is the featured image!</p>
    {% endif %}
{% endfor %}

In this example, we use a ternary operator to add the class is-featured only to the first item. This is the cleanest approach when you need to output all items but want to style the first one differently.

Fetching Only the First Item with .one()

In many scenarios, you don't actually need to loop through every item. If your goal is simply to display the first asset or the most recent entry, looping through everything is inefficient.

In modern Craft CMS (v3, v4, and v5), when you are working with an Element Query (like craft.entries or an Assets field), you should use the .one() method. This executes the database query and returns a single element object rather than an array of objects.

{# Fetching the first image from an Assets field #}
{% set featuredImage = entry.myAssetsField.one() %}

{% if featuredImage %}
    <img src="{{ featuredImage.url }}" alt="{{ featuredImage.title }}">
{% endif %}

A Note on .first() vs .one()

If you are looking at older Craft CMS codebases or tutorials, you might see the .first() method. While .first() still works in many contexts for backward compatibility, .one() is the standard method in modern Craft development for fetching a single element from a query. It is more explicit and aligns with how Craft handles database execution.

Targeting the First Item in a Standard Array

Sometimes you aren't working with an Element Query, but rather a standard PHP/Twig array. This often happens when working with RSS feeds, JSON data, or the results of a Twig filter like |split.

In these cases, .one() will not work because the data is not a query object. Instead, you have two primary options: the |first filter or array index syntax.

The |first Filter

The |first filter is the most readable way to grab the first element of an array in Twig.

{% set updates = craft.feeds.getFeedItems('https://example.com/feed.rss') %}
{% set latestUpdate = updates|first %}

{% if latestUpdate %}
    <h2>{{ latestUpdate.title }}</h2>
{% endif %}

Array Index Syntax

You can also use the [0] syntax common in most programming languages. In Twig, arrays are zero-indexed, meaning the first item is always at position 0.

{% set primaryLocale = craft.app.sites.allSiteIds[0] %}

Warning on Dev Mode: If you use [0] on an empty array while Craft's devMode is enabled, Twig will throw an error because the index does not exist. The |first filter is generally safer as it will simply return null if the array is empty.

Handling Empty States Safely

One of the most common causes of template errors is trying to access properties on a "null" object. This happens when you assume a "first item" exists, but the field is actually empty. Always wrap your logic in a conditional check.

The "Good" Way (Safe)

{% set firstItem = entry.myAssetsField.one() %}

{% if firstItem %}
    {# This only runs if an item actually exists #}
    {{ firstItem.url }}
{% endif %}

The "Bad" Way (Risky)

{# This will crash your site if no image is selected! #}
<img src="{{ entry.myAssetsField.one().url }}">

Frequently Asked Questions

What is the difference between loop.first and .one()?

loop.first is used inside a for loop to identify the first iteration while still processing the rest of the items. .one() is used on an Element Query to fetch only the first matching item from the database, ignoring all others. Use .one() for performance when you only need a single item.

Can I use .one() on a Matrix field?

Yes. Matrix fields return an Element Query. If you want to grab only the first block of a specific type, you can use: {% set block = entry.myMatrixField.type('text').one() %}.

Why does my template show an error when using [0]?

This usually happens because the array is empty. Twig cannot access the 0-index of nothing. To fix this, either use the |first filter or check if the item is defined first: {% if myArray[0] is defined %}.

Key Takeaways

  1. Inside a loop: Use {% if loop.first %} to apply unique logic or styles to the first item in a sequence.
  2. Element Queries: Use .one() to efficiently fetch a single entry, asset, or category from the database.
  3. Standard Arrays: Use the |first filter for the best balance of readability and safety when dealing with non-element data.
  4. Safety First: Always use an {% if item %} check before outputting properties to prevent errors on empty fields.
  5. Performance: If you only need the first item, avoid calling .all() and then picking the first one; use .one() to keep your database queries lean.