michtio/craftcms-claude-skills / skills/craft-site
craft-site
VerifiedCraft CMS 5 front-end Twig development — atomic design, template architecture, components, Vite buildchain. Covers atoms/molecules/organisms, props/extends/block patterns, layout chains, view routing, content builders, image presets, Tailwind named-key collections, multi-brand CSS tokens, JavaScript boundaries (Alpine/DataStar/Vue, tabs, accordions), Vite asset loading, and front-end auth (login, registration, password reset, profiles).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| references/atomic-design.md | markdown | 11.1 KB |
| references/atomic-patterns.md | markdown | 12.3 KB |
| references/auth-account.md | markdown | 18.1 KB |
| references/auth-flows.md | markdown | 22.5 KB |
| references/boilerplate-routing.md | markdown | 14.7 KB |
| references/component-inventory.md | markdown | 11.4 KB |
| references/composition-patterns.md | markdown | 14.5 KB |
| references/element-partials.md | markdown | 7.9 KB |
| references/example-templates.md | markdown | 14.2 KB |
| references/feeds.md | markdown | 8.4 KB |
| references/headless.md | markdown | 15.4 KB |
| references/image-presets.md | markdown | 14.0 KB |
| references/javascript-boundaries.md | markdown | 12.4 KB |
| references/multi-site-patterns.md | markdown | 13.2 KB |
| references/search.md | markdown | 10.3 KB |
| references/tailwind-conventions.md | markdown | 6.8 KB |
| references/template-caching.md | markdown | 14.2 KB |
| references/third-party-integration.md | markdown | 8.6 KB |
| references/twig-collections.md | markdown | 8.2 KB |
| references/vite-buildchain.md | markdown | 9.3 KB |
references/element-partials.md
View on GitHub# Element Partials
How to use `entry.render()` and the `_partials/` template directory in Craft CMS 5 for reusable element rendering. Element partials are a front-end feature — the CP does not use them. For CP element display (chips, cards, table rows), see the craftcms skill's `element-index.md`.
## Documentation
- Element partials: https://craftcms.com/docs/5.x/system/elements.html#rendering-elements
## Common Pitfalls
- Forgetting to create the partial template — `render()` silently falls back to a `<p>` tag with the element's title. No error, no warning — just a plain text title where your card should be.
- N+1 queries inside partials — use `.eagerly()` for any related element queries. Each partial renders independently, so without eager loading, every card in a grid fires separate queries.
- Assuming `render()` works in the CP — it's front-end only (`TEMPLATE_MODE_SITE`).
- Hardcoding the partial path instead of using the convention — the lookup path is automatic. Don't `{% include %}` the partial manually when `entry.render()` works.
- Overriding an entry type's handle per field and expecting the partial to follow — it does, but only on Craft 5.10.14+. On older versions the override is ignored for lookup, so the partial must live under the original handle.
## Contents
- [How It Works](#how-it-works)
- [Template Lookup Path](#template-lookup-path)
- [Available Variables](#available-variables)
- [Passing Custom Variables](#passing-custom-variables)
- [Common Patterns](#common-patterns)
- [Configuration](#configuration)
## How It Works
Every element in Craft 5 has a `render()` method that looks for a matching template in `_partials/`, renders it, and returns the HTML as a `Twig\Markup` object (safe for direct output).
```twig
{# Render a single entry #}
{{ entry.render() }}
{# Render a list of entries #}
{% for entry in craft.entries().section('blog').limit(10).all() %}
{{ entry.render() }}
{% endfor %}
{# Render with custom variables #}
{{ entry.render({ size: 'compact', showExcerpt: false }) }}
```
If no matching template exists, `render()` falls back to a `<p>` tag containing the element's title — no error is thrown.
## Template Lookup Path
`render()` builds a list of candidate templates and renders the first one that exists (lowest priority number wins). Since 5.8.0 plugins can add or reorder candidates through `Element::EVENT_RENDER`.
### Priority 1: Overridden entry type handle (5.10.14+)
```
_partials/{refHandle}/{overriddenHandle}.twig
```
Entries only, and only when the entry type's handle is overridden for the field or section it's used in (per-usage overrides, 5.6.0+). Before 5.10.14 this candidate didn't exist: a `cta` type renamed to `richTextCta` inside a CKEditor field still rendered `_partials/entry/cta.twig` (craftcms/cms#18968).
### Priority 2: Type-specific partial
```
_partials/{refHandle}/{providerHandle}.twig
```
- `{refHandle}` — the element's reference handle: `entry`, `asset`, `user`, `address`
- `{providerHandle}` — the field layout provider's handle: for entries, this is the **original entry type handle**
Examples:
```
_partials/entry/article.twig ← article entry type
_partials/entry/blogPost.twig ← blogPost entry type
_partials/asset/image.twig ← (if assets had type-specific layouts)
_partials/user.twig ← user fallback (no type handle)
```
### Priority 3: Generic fallback
```
_partials/{refHandle}.twig
```
Examples:
```
_partials/entry.twig ← fallback for all entry types
_partials/asset.twig ← fallback for all assets
```
The most specific existing template wins. The generic fallback catches everything else.
## Available Variables
Inside the partial template, the element is available under its reference handle:
| Element Type | Variable Name |
|-------------|---------------|
| Entry | `entry` |
| Asset | `asset` |
| User | `user` |
| Address | `address` |
| Custom element | The element's `refHandle()` return value |
For nested entries (Matrix, CKEditor), the `entry` variable has `owner` and `field` properties for accessing the parent context.
## Passing Custom Variables
Pass an associative array to `render()`. The variables merge into the template context:
```twig
{{ entry.render({ size: 'hero', showMeta: true, imagePreset: 'wide' }) }}
```
In the partial, guard with defaults:
```twig
{# _partials/entry/article.twig #}
{% set size = size ?? 'default' %}
{% set showMeta = showMeta ?? true %}
{% set imagePreset = imagePreset ?? 'card' %}
<article class="article article--{{ size }}">
{% set image = entry.featuredImage.eagerly().one() %}
{% if image %}
{{ image.render({ preset: imagePreset }) }}
{% endif %}
<h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3>
{% if showMeta %}
<time datetime="{{ entry.postDate | atom }}">
{{ entry.postDate | date('M j, Y') }}
</time>
{% endif %}
</article>
```
## Common Patterns
### Blog card grid
```twig
{# templates/blog/index.twig #}
{% set entries = craft.entries()
.section('blog')
.with(['featuredImage', 'author', 'topics'])
.limit(12)
.all() %}
<div class="grid grid-cols-3 gap-6">
{% for entry in entries %}
{{ entry.render({ size: 'card' }) }}
{% endfor %}
</div>
```
### Varying layout by entry type
The type-specific lookup means different entry types render differently without conditionals:
```
_partials/entry/article.twig ← article layout (image + excerpt)
_partials/entry/video.twig ← video layout (embed + duration)
_partials/entry/event.twig ← event layout (date + venue)
```
```twig
{# All entries render with their own partial — no if/switch needed #}
{% for entry in entries %}
{{ entry.render() }}
{% endfor %}
```
### Nested element rendering
Matrix entries and CKEditor nested entries also support `render()`:
```twig
{# Render Matrix blocks #}
{% for block in entry.contentBlocks.all() %}
{{ block.render() }}
{% endfor %}
```
Each block type gets its own partial: `_partials/entry/heroBlock.twig`, `_partials/entry/textBlock.twig`, etc.
### Eager loading inside partials
Use `.eagerly()` on **custom relation fields** to avoid N+1 queries when rendering a list:
```twig
{# _partials/entry/article.twig #}
{% set image = entry.featuredImage.eagerly().one() %} {# custom Assets field #}
{% set categories = entry.topics.eagerly().all() %} {# custom relation field #}
{% set author = entry.author %} {# native attribute — access directly #}
```
`.eagerly()` batches queries across all partials in the same render cycle.
**Native attributes can't be `.eagerly()`-loaded.** `entry.author` (also `entry.authors`, an asset's `uploader`, a user's `photo`) returns the element directly — not a query — so there's no `.eagerly()`/`.one()` to chain; `entry.author.eagerly()` throws. Since Craft 5.8.0 `entry.author`/`entry.authors` batch themselves across the query result, so a bare `entry.author` in a partial costs one query per listing; anything below the author (`author.photo`, author fields) does not, so cover it with `.with(['author.photo'])` on the **outer** query, as the Blog card grid above does with `.with(['author'])`. See `craft-content-modeling` → `relations-and-eager-loading.md` for the full `.with()`-vs-`.eagerly()` rules.
### Asset partials
```twig
{# _partials/asset.twig #}
{% set preset = preset ?? 'default' %}
{% if asset.kind == 'image' %}
<img src="{{ asset.url }}"
width="{{ asset.width }}"
height="{{ asset.height }}"
alt="{{ asset.alt ?? asset.title }}"
loading="lazy">
{% else %}
<a href="{{ asset.url }}">{{ asset.title }}</a>
{% endif %}
```
## Configuration
| Setting | Default | Purpose |
|---------|---------|---------|
| `partialTemplatesPath` | `'_partials'` | Base directory within `templates/` for partial lookup |
```php
// config/general.php
->partialTemplatesPath('_components/partials')
```
Or via environment variable: `CRAFT_PARTIAL_TEMPLATES_PATH`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |