Empty states
Use the koala-empty-state
tag helper for any "no items yet" surface — page-level lists, tab content, sub-sections, settings panels,
side trays, and modals. Renders an icon-circle, sentence-case heading, optional body, and optional CTA.
Default size
Page-level and tab-level empties. Use everywhere unless the container is narrow (side tray, dropdown).
<koala-empty-state icon="Users" title="No team members yet"
cta-href="@InviteTeamMember.Route()" cta-label="Invite team member">
Invite your first team member to get started.
</koala-empty-state>
Small size
For narrower contexts: side trays, dropdown menus, compact inline blocks. Tighter padding, smaller icon-circle and title.
No eligible users
All team members already have access to this branch or have partner-wide access.
<koala-empty-state size="Small" icon="Users" title="No eligible users">
All team members already have access to this branch or have partner-wide access.
</koala-empty-state>
Filtered vs truly empty
On list pages, branch the empty state on whether the user has filters applied.
Use icon="Search"
for "no results match" and a "Clear filters" CTA; use the entity icon (Quote, Transaction, Users, Building, etc.)
for the truly-empty state and a "Create" CTA.
Icon mapping
Match the icon to the entity. Don't pick "random" icons.
| Empty of | Icon |
|---|---|
| Quotes | Quote |
| Transactions | Transaction |
| Notes | MessageSquare |
| Activity | Activity |
| Fees | CreditCard |
| Discounts | Discount |
| Stakeholders / single user | User |
| Team / users (collection) | Users |
| Branches | Building |
| Partners / partner memberships | Partner |
| Filtered "no match" | Search |
| Settings / config gated on key | Key |
| Documents (terms, etc.) | FileText |
| Informational notice | Info |
| Client welcome / "moving again" | House |
Usage guidance
When and where to use empty states.
| Do | Don't |
|---|---|
| Branch the message on filtered vs truly-empty | Use for error states (use alert banners instead) |
| Use the matching entity icon (see mapping above) | Pick "random" icons — match to the entity |
Use size="Small" in side trays, dropdowns, compact blocks |
Show alongside populated content |
| Add a CTA when the user can create their first item | Use for form validation messages |
| Use sentence case for titles ("No quotes yet") | Nest multiple empty states on the same page |