Skip to content

Latest commit

 

History

History
126 lines (92 loc) · 5.41 KB

template-syntax.md

File metadata and controls

126 lines (92 loc) · 5.41 KB

Astro template syntax

Astro docs: Template syntax

Astro's template syntax belongs to the .astro compiler. A .razor file uses Razor syntax: @expression, @if, @foreach, @code { }, @attribute, @namespace.

The mapping

Astro Razor
{value} @value
{items.map(i => <li>{i}</li>)} @foreach (var i in items) { <li>@i</li> }
{cond && <p>yes</p>} @if (cond) { <p>yes</p> }
{cond ? a : b} @(cond ? a : b)
<Fragment> Nothing needed — a component may return sibling elements. Use @: for a bare line of text.
--- frontmatter @code { } for members, @{ } for statements
set:html={raw} @((MarkupString)raw)

@code versus @{ }

@code { } declares class members — fields, properties, methods. @{ } is a block of statements that runs as the component renders, which is the nearer equivalent to Astro's --- fence:

@{
    var total = Items.Sum(i => i.Price);
    var label = total > 100 ? "Free delivery" : "Standard delivery";
}

<p>@label</p>

Async work goes in OnInitializedAsync, not in either — a Razor component cannot await mid-markup.

Escaping @

@ is Razor's transition character, so a literal one is doubled. This bites most often in CSS at-rules inside a <style> block:

@@media (min-width: 600px) { .box { padding: 1rem; } }

It renders as @media. Email addresses in markup need it too: name@@example.com.

Template directives

There are two questions here with different answers. Applied to your component means an .astro file writes the directive on the C# component's tag, and Astro handles it before AstroSharp sees anything. Written inside means the .razor file wants the directive on markup of its own — where it cannot have it, because a directive is compiler syntax and the Razor compiler is not Astro's.

Directive Applied to your component Written inside a .razor file
set:html, set:text Works. Arrives as the default slot. @((MarkupString)html)
class:list Works. Arrives as a computed class prop. Astro.ClassList(...)
define:vars — Astro.Vars(...), on a <style>
is:global, is:inline — Work, on <style> and <script>
is:raw Works on the tag. No equivalent, and none needed — see below
transition:* Works on the tag. No equivalent: the scope attributes are compiler-generated. See View transitions.
client:* Rejected at build time; client:only fails in the browser. See Islands architecture. —
server:defer Unsupported. See Server islands. —

is:raw tells Astro's compiler to stop interpreting {...} and components inside an element. A .razor file has neither, so there is nothing to opt out of; Razor's own escape is @@, above.

Astro.ClassList

<article class:list={['card', className, { featured: isFeatured, wide: width > 600 }]}>
<article class="@Astro.ClassList("card", Class, new { featured = IsFeatured, wide = Width > 600 })">

A string contributes itself, a list contributes each entry recursively, and an object or dictionary contributes the names whose values are truthy — so null, false, "" and 0 contribute nothing. Pass a dictionary for a name C# cannot spell as an identifier:

<div class="@Astro.ClassList(new Dictionary<string, bool> { ["is-active"] = IsActive })">

This mirrors Astro's own implementation, which is clsx: order is the order written, and nothing is de-duplicated — both matter in CSS, where the last declaration of equal specificity wins. Numbers are formatted invariantly, for the same reason everything else interpolated is.

Numbers and dates are invariant

A value interpolated into markup is formatted the way JavaScript formats one — invariantly — rather than the way .NET does by default, which is the culture of whatever machine ran the build.

@* 0.5 everywhere, not "0,5" on a machine with a comma decimal separator *@
<div style="opacity: @Scale">…</div>

This is a correctness rule rather than a preference. opacity: 0,5 is not a number, so the browser drops the declaration — and the same source produced different HTML on a developer's laptop and in CI, silently. It also matches what is being mirrored: ${0.5} in a template literal is "0.5" everywhere, and JavaScript makes you ask for localization.

Ask for it the same way and it is honoured:

<p>@Price.ToString("C", new CultureInfo("de-DE"))</p>

Limitations

No Astro-shaped C# syntax. There is no --- fence and no {expression} in a .razor file, and no .acs-style format. Components are Razor, which is the trade that buys working editor tooling on day one.

Razor's parser reads <bool> as a tag. A generic call in markup needs explicit parens:

@(Astro.Locals.Get<bool>("flag"))

A double-quoted attribute ends at the first inner double quote, which is why <AstroComponent Props='...'> uses single quotes. A call is fine — class="@Astro.ClassList("card")" parses, because Razor tracks the balanced parentheses of an implicit expression. It is a bare expression containing a string, as Props takes, that ends early.