Custom Data Source

8 min

Overview

The custom data source lets you define a static list of items directly inside views.json. No API call is made — the items are embedded in the configuration and available immediately. It is useful for fixed navigation links, static option lists, hard-coded tabs, or any list whose content never changes at runtime.

When to use this

Use custom for lists that are fully controlled by the developer and do not require fetching from any external source. If the items need to come from an API or change based on user state, use a different data source type.

Basic Example

{
    "type": "custom",
    "contextKey": "navLinks",
    "items": [
        { "label": "Home", "url": "/home" },
        { "label": "Archive", "url": "/archive" },
        { "label": "About", "url": "/about" }
    ]
}

This makes the three items available as $context.navLinks immediately, with no API request. Child components can iterate over the list and render each item using its label and url properties.

Configuration

Type-specific properties

Property	Type	Default	Description
items	array	—	Required. The static list of items. Each element can be any JSON object.

Common configuration (inherited)

All common data source properties apply — contextKey, limit, offset, randomize, etc. batchSize, maxCacheAge, and preventSSRCache have no effect since there is no API call.

For more details, see Data Sources Overviewda

Advanced Features

Using conditional values in items

Individual item properties can use $context values for dynamic labels or URLs, even though the list itself is static:

{
    "type": "custom",
    "contextKey": "tabs",
    "items": [
        { "label": "Latest", "filter": "latest" },
        { "label": "Popular", "filter": "popular" }
    ]
}

Combining with randomize

The randomize property works with custom items — useful for rotating static promotional banners:

{
    "type": "custom",
    "contextKey": "promos",
    "randomize": true,
    "limit": 1,
    "items": [
        { "image": "promo-a.jpg", "url": "/offer-a" },
        { "image": "promo-b.jpg", "url": "/offer-b" }
    ]
}

Testing Notes / Edge Cases

limit and offset work normally: Even though items are static, limit and offset apply as expected. A limit: 1 with randomize: true picks one random item.

Empty items array: An empty array [] is valid and produces an empty list. The component renders its empty state.

Large static lists: For lists with many items, consider whether a json data source with a local resource file is more maintainable — it keeps items out of views.json.

Data Sources Overviewda

JSON Data Sourcesj

TODO insert link to Context Data Source