Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic

Pass one row per entry, numbered, so a validation message can say which row is wrong.

A contacts list
Add a row, then remove one. The numbering and the remove buttons' accessible names follow. Index the field names, not just the labels: Contacts[0].Name and Contacts[1].Name are what let model binding rebuild the collection, and an unindexed Name posts one value and loses the rest. Razor has no onRemove switch: the remove control shows once the row count is above min, so setting min to the row count locks the rows, which React does by omitting onRemove.
1
2
Show code
<app-repeater name="Contacts" add-label="Add contact" remove-label="Remove contact" min="1">
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="Contacts[0].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="Contacts[0].Email" type="email" /></div>
        </div>
    </app-repeater-row>
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="Contacts[1].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="Contacts[1].Email" type="email" /></div>
        </div>
    </app-repeater-row>
</app-repeater>

Handling the post

Both controls are buttons with a namespaced name, derived from the repeater's name attribute; webority-ui.js posts the form with it, so the page must load that script. Set it to the collection name and the handler reads like the model.

The page model
Add and remove are a server round trip: the page's OnPost handler does what the playground does here. Add and remove re-render the page rather than saving, so the user is not shown validation errors for rows they have not filled in yet. Always set name when a page has two repeaters: without it both post the same keys and the server cannot tell which list the click belonged to. The remove value is the zero-based collection index; the number the user sees is one-based, and the two are deliberately different so the handler can index directly.
1
Show code
public IActionResult OnPost()
{
    if (Request.Form.ContainsKey("Visitors.add"))
    {
        Visitors.Add(new VisitorInput());
        return Page();
    }
    if (int.TryParse(Request.Form["Visitors.remove"], out int i))
    {
        Visitors.RemoveAt(i);            // the posted value is zero-based
        return Page();
    }

    if (!ModelState.IsValid) return Page();
    // a real save
}

Minimum and maximum

Set min and max to keep the row count in range; remove hides at min and add disables at max.

At least one, at most three
Add rows until the button greys out; remove until the last row's control vanishes. Removability is boolean-driven on React and threshold-driven on Razor. React's AppRepeater hides every remove control when onRemove is omitted, regardless of row count. The Razor tag helper has no such switch. It always shows the control once rows.Count > min. Setting min to the current row count is the nearest equivalent (read-only until a row is added), but it is not the same guarantee: adding a row past that count re-enables removal, where React's rows stay permanently read-only until the caller passes an onRemove.
1
2
3
Show code
<app-repeater name="Sites" add-label="Add contact" min="1" max="3">
    <app-repeater-row><app-input label="Name" name="Sites[0].Name" /></app-repeater-row>
    <app-repeater-row><app-input label="Name" name="Sites[1].Name" /></app-repeater-row>
    <app-repeater-row><app-input label="Name" name="Sites[2].Name" /></app-repeater-row>
</app-repeater>

Empty state

Give an empty repeater a message, so the lone add button does not read as broken.

No rows yet
Say what the list is for, so the Add button has context.
No contacts yet. Add at least one for site access.
Show code
<app-repeater name="Zones" add-label="Add contact" empty-text="No contacts yet. Add at least one for site access."></app-repeater>

Per-row labels

Label each row with its role or category, shown in the header band beside its number.

Label each row
The label sits above the fields, clear of them, and pairs with the row number.
Primary contact1
Contact2
Show code
<app-repeater name="LabelledContacts" add-label="Add contact" remove-label="Remove contact" min="1">
    <app-repeater-row label="Primary contact">...</app-repeater-row>
    <app-repeater-row label="Contact">...</app-repeater-row>
</app-repeater>

With react-hook-form

React-only concept: react-hook-form's useFieldArray is the intended pairing for the React AppRepeater. The Razor tag helper has no client-side form library; the equivalent is ASP.NET Core model binding with indexed row names, which every example on this page already uses.

Razor's equivalent is model binding, not a form library
The React example wires useFieldArray to get stable row ids and array mutation for free. Razor rows are server-rendered from the model and posted with indexed names, Team[0].Name and Team[1].Name. There is no client-side array state to manage; the round trip through OnPost is the array mutation.
1
2
Show code
<app-repeater name="Team" add-label="Add contact" min="1">
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="Team[0].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="Team[0].Email" type="email" /></div>
        </div>
    </app-repeater-row>
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="Team[1].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="Team[1].Email" type="email" /></div>
        </div>
    </app-repeater-row>
</app-repeater>

Custom row rendering

Put any markup in a row, such as a searchable select beside a number field.

Line items
A different row shape entirely, inside the same repeater frame.
1
Consulting Hosting Support Licence
Show code
<app-repeater name="LineItems" add-label="Add line item" remove-label="Remove line item" min="1">
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-8">
                <app-select label="Item" name="LineItems[0].Kind">
                    <app-option value="Consulting">Consulting</app-option>
                    <app-option value="Hosting">Hosting</app-option>
                    <app-option value="Support">Support</app-option>
                    <app-option value="Licence">Licence</app-option>
                </app-select>
            </div>
            <div class="col-sm-4"><app-number-input label="Qty" name="LineItems[0].Qty" min="1" value="1" /></div>
        </div>
    </app-repeater-row>
</app-repeater>

Every option

Every value of every prop, one cell each.

rows

rows: one app-repeater-row per entry
1
2

renderRow

renderRow: the markup inside each app-repeater-row draws the fields
1
Consulting Hosting

rowLabel

app-repeater-row label="…": the header band text of one row
Primary contact1
Contact2

onAdd

add button: posts {name}.add, and the page appends a row
1

onRemove

remove button: posts {name}.remove, and the page removes the row
1
2

min / max

min="0" (default): can remove down to zero
1
min="1": last row's remove control hidden
1
max="2": at max, add button disabled
1
2
max="0" (default): add button never disables
1
2
3
4
5
6

emptyText

empty-text set, no rows
No contacts yet. Add at least one for site access.
empty-text unset, no rows: a lone Add button

addLabel

add-label="Add line item"
1

addVariant

add-variant="soft" (default)
1
add-variant="solid"
1
add-variant="outline"
1
add-variant="ghost"
1
add-variant="glass"
1
add-variant="link"
1

removeLabel

remove-label="Remove line item": the accessible name of each remove control
1
2

numbered

numbered="true" (default)
1
2
numbered="false"

className

class: extra classes on the repeater
1

name

name="NameA": namespaces the add and remove keys
1

add-form-action

add-form-action: where the add button posts; omit it to post to the form's own action
1

Guidance

What to do, and what to avoid.

Use it when

  • A form needs one or more of the same group of fields.
  • The count is decided by the user, not the schema.
  • Each entry has more than one field: a name and an email, a description and an amount.

Reach for something else when

  • The user is picking from a known list of options. → AppSelect mode="multiple"
  • It is a single repeated value, like a list of tags. → AppSelect mode="tag"
  • The rows are existing records to manage. → AppDataTable
  • The count is fixed by the schema. → plain fields

Name the actions and number rows

Do
1

Specific add and remove labels ("Add contact"), a minimum so the form cannot reach an unsubmittable state, and numbered rows validation can point at.

Avoid

A generic "Add another", no remove control at all, and no numbering, so "Row 2 email is invalid" has nothing to point at.

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

solid soft outline ghost link glass
1
2
React, generated from the controls
<AppRepeater
  rows={rows}
  addLabel="Add contact"
  removeLabel="Remove contact"
  onAdd={() => { addRow(); /* onAdd */ }}
  onRemove={(i) => { removeRow(i); /* onRemove */ }}
  renderRow={(row, i) => /* name + email fields */ ...}
/>
Razor, the same props
<app-repeater name="PgContacts" add-label="Add contact" remove-label="Remove contact">
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="PgContacts[0].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="PgContacts[0].Email" type="email" /></div>
        </div>
    </app-repeater-row>
    <app-repeater-row>
        <div class="row g-2">
            <div class="col-sm-6"><app-input label="Name" name="PgContacts[1].Name" /></div>
            <div class="col-sm-6"><app-input label="Email" name="PgContacts[1].Email" type="email" /></div>
        </div>
    </app-repeater-row>
</app-repeater>

10 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
add-labeldefault Add another string Add another Text of the add button.
remove-labeldefault Remove row string Remove row Accessible name of each remove control. The row number is added, as in "Remove row 2".
empty-textdefault - string - Shown in place of the rows when there are none.
mindefault 0 int 0 Rows at or below this count cannot be removed.

Less common 6 props

PropTypeDefaultDescription
namedefault repeater string repeater Namespaces the add and remove buttons. Set it to the collection name so two repeaters on a page cannot collide.
add-variantdefault soft ghost | glass | link | outline | soft | solid soft The add control's variant: an AppButton variant such as solid, outline or ghost, or link for a small text link with a plus icon. An unknown value warns in development.
maxdefault 0 int 0 Adding is disabled at this count.
numbereddefault true bool true Show the row index.
add-form-actiondefault - string - Where the add button posts. Omit to post to the form's own action.
labeldefault - string - Set on an app-repeater-row. The label sits in the row's top-left header band. Omit it to leave the row unlabelled.

Screen reader

2 notes
  • Each remove control is an icon button named by removeLabel and the row number, such as "Remove contact 2".
  • The add button shows its addLabel as visible text and is disabled once max rows exist.

Do and avoid

1 pairs

Name the actions and number rows

Do
1

Specific add and remove labels ("Add contact"), a minimum so the form cannot reach an unsubmittable state, and numbered rows validation can point at.

Avoid

A generic "Add another", no remove control at all, and no numbering, so "Row 2 email is invalid" has nothing to point at.