Empty | NDS - Vanilla National Design System

Generic Container

Add nds-empty to any block element. When it has no child elements, the placeholder renders centered inside.

Empty Div

In Lists

On <ul> and <ol> elements the placeholder is injected as an <li> so the list structure stays valid.

Empty Unordered List

In Tables

Place nds-empty on the <table> itself. The placeholder row spans every column using colspan derived from the header, and a <tbody> is created automatically when one is missing.

Empty Table

Name	Status	Updated

Custom Message & Icon

Override the default text with data-empty-message and the default glyph with data-empty-icon. Either attribute updates its rendered element in place when the value changes at runtime.

Notifications Empty

Live Content Updates

The placeholder reacts automatically to DOM changes. Adding a real child hides it; removing the last real child brings it back. No manual refresh needed.

Reactive List

Built-in Features

Auto-initialization

Activates on any element with nds-empty. New containers added to the DOM later are picked up automatically.

Parent-Adaptive Markup

Injects a valid child for the parent tag: <li> in lists, a spanning <tr> with <td colspan> in tables, a <div> elsewhere.

Bilingual Defaults

Renders Arabic or English text based on the page lang attribute with no configuration.

Live Reactivity

Placeholder appears when the container becomes empty and disappears the moment real content is added back.

Custom Message Override

Set data-empty-message on the container to replace the default text. Updates live when the attribute changes.

Programmatic Control

Call NDS.Empty.refresh(el) to force re-evaluation of a specific container from application code.

Usage Guidelines

Best Practices

Use nds-empty on any container that can legitimately have zero items: search results, filtered lists, data tables, notification feeds, dashboards, user-generated collections
Prefer nds-empty over a hand-rolled placeholder so all empty states across the site look and behave consistently
Do not use it for loading or in-progress states. Use the Loading component while data is being fetched, then let nds-empty take over once the request resolves with no results
Do not use it to communicate errors. Use an Alert with data-status="error" so the user understands something went wrong rather than that the result set is genuinely empty
Write data-empty-message so it answers "why is this empty and what can I do next?" For example, "No results match your search" beats "Empty" because it implies the user can adjust the query
Keep custom messages to a single short sentence. Longer guidance belongs in a paragraph outside the container or in linked help content
Make sure the container has enough height for the placeholder to breathe. A minimum height of roughly 240 to 320 pixels keeps the icon and message visually centered
Do not mix nds-empty with conditionally rendered "no results" markup in the same container. Pick one so the placeholder never appears twice
When a table column count changes after initial render, call NDS.Empty.refresh(el) so the placeholder row picks up the new colspan

Data Attributes

Attribute	Description
`data-empty-message`	Set on the `.nds-empty` container to override the default text. Any non-empty string wins over the built-in Arabic or English default. Changing the value at runtime updates the rendered message in place.
`data-empty-icon`	Set on the `.nds-empty` container to override the default icon. Value is the full `class` string applied to the placeholder's `<i>`. Use any icon system: UI icon (`nds-icon nds-hgi-search-01`) or content-font icon (`hgi hgi-stroke hgi-notification-off-01`). Changing the value at runtime updates the rendered icon in place.

JavaScript API

The NDS.Empty API auto-initializes at page load and watches the DOM for new .nds-empty containers. Use NDS.Empty.refresh() when you need to force re-evaluation after an external DOM operation the observer cannot see (for example, a column-count change on a table).


// ── Initialization ───────────────────────────────────
// The loader calls this automatically at page load.
// Call again if you add .nds-empty containers via innerHTML before
// the DOM observer has a chance to pick them up.
NDS.Empty.init();

// ── Force re-evaluation of a single container ────────
// Usage: after changing a table's column count, adding/removing
// placeholder-relevant state, or any programmatic change the
// childList observer does not surface.
const table = document.querySelector('#my-table');
NDS.Empty.refresh(table);

// ── Localization ─────────────────────────────────────
// Default message language is picked from <html lang="...">
// via NDS.isArabic. To override for a single instance, set
// data-empty-message on the element itself.
//
//   <div class="nds-empty" data-empty-message="No items yet"></div>
//
// Changing data-empty-message at runtime updates the rendered
// placeholder automatically:
container.setAttribute('data-empty-message', 'Try a different filter');