Set up an Article List
This component will automatically list the available articles from your data loader, with options for sorting and filtering.
There are three formats available, and you can preview them at the bottom of this page.
Article Setup
If you haven't done so already, please see the Article Setup page for instructions on how to perform the initial setup.
Before you use this component, you will need to create a new post and add the appropriate frontmatter.
Usage
You can simply add <VpvArticleList /> to the body of your blog post.
If you something doesn't look right, check your frontmatter! You can compare it with the example in Article Header.
I recommend the following customizations for some common use cases:
Recommended Customizations
On a blog post, such as for a 'read more' section:
Use the vertical format, and set the maxCards prop to 2. This will display the first two posts in the list. You can also set it to match the category of the current post, as well as exclude the current post from the list.
On a blog home page:
Use the horizontal format. Additionally, set the frontmatter VitePress layout to home. (see here)
Optional Functionality
Display Formats
There are three formats available, and you can preview them at the bottom of this page.
format="vertical"(default) - Cards are displayed in a vertical grid layoutformat="horizontal"- Cards are displayed in a horizontal scrolling layoutformat="debug"- Displays the raw JSON data of the filtered articles for debugging purposes
Card Display Options
hide* Props
These props allow you to hide certain elements from the article cards, while still keeping the information available in the frontmatter for other components.
- default
hideAuthorisfalse - default
hideDateisfalse - default
hideImageisfalse - default
hideCategoryisfalse - default
hideTagsisfalse - default
hideDomainisfalse
dateFormat
This prop allows you to specify the format of the date. It defaults to long. You can set it to the following values:
dateFormat="long"(default, example: "October 30, 2025")dateFormat="short"(example: "Oct 30, 2025")dateFormat="iso"(example: "2025-10-30")- A custom format string, such as
:dateFormat="'yyyy-MM-dd HH:mm'"(example: "2025-10-30 17:00")
Other Display Options
disableLinks: Prevents the cards from being clickable links (default:false)titleLines: Limits the number of lines for the title displayexcerptLines: Limits the number of lines for the excerpt displaymaxCards: Limits the total number of cards displayed
Filtering & Sorting
Basic Filtering
featuredOnly: Only display articles marked as featured (default:false)renderDrafts: Include articles withstatus: draft(default:false)
Author Filtering
filterAuthors: Only show articles by specific authors. Can be a single author string or array of author stringsexcludeAuthors: Exclude articles by specific authors (array of strings)
Category Filtering
filterCategories: Only show articles from specific categories (array of strings)excludeCategories: Exclude articles from specific categories (array of strings)
Tag Filtering
filterTags: Only show articles that have ANY of the specified tags (array of strings)excludeTags: Exclude articles that have ANY of the specified tags (array of strings)
URL Filtering
excludeURLs: Exclude specific article URLs from the list (array of strings)
Date Range Filtering
startDate: Only show articles published on or after this date (Date, string, or null)endDate: Only show articles published on or before this date (Date, string, or null)
Sorting
sortOrder: Sort articles by date"descending"(default) - Newest articles first"ascending"- Oldest articles first
Data Source Customization
articlesDataKey & postsDataKey
If you overrided the default export keys, you can use the following props to select the correct data. Note that most users will not need to use these props:
articlesDataKey: The key of the articles data to use (ex.demoArticles)postsDataKey: Legacy prop for backward compatibility (ex.demoPosts)
authorsDataKey
If you overrided the default export keys, you can use the following prop to select the correct data. Note that most users will not need to use this prop:
authorsDataKey: The key of the authors data to use (ex.demoAuthors)
Kitchen Sink Example
Here's a silly example that uses every single prop available (don't actually do this):
vue
<VpvArticleList
:articles="customArticleArray"
articlesDataKey="myCustomArticles"
authorsDataKey="myCustomAuthors"
format="horizontal"
hideAuthor
hideDate
dateFormat="iso"
hideImage
hideCategory
hideTags
hideDomain
disableLinks
:titleLines="2"
:excerptLines="3"
:maxCards="5"
sortOrder="ascending"
:filterAuthors="['john', 'jane']"
:excludeAuthors="['bob']"
:filterCategories="['tech', 'news']"
:excludeCategories="['draft']"
:filterTags="['vue', 'javascript']"
:excludeTags="['deprecated']"
:excludeURLs="['/old-post', '/another-old-post']"
featuredOnly
renderDrafts
startDate="2024-01-01"
endDate="2024-12-31"
/>Demo
Horizontal Card Format
The following code was used:
vue
<VpvArticleList
format="horizontal"
postsDataKey="demoBlogData"
:excludeURLs="[
'/demo-blog/december',
'/demo-blog/november',
]"
/>Vertical Card Format
The following code was used:
vue
<VpvArticleList
format="vertical"
postsDataKey="demoBlogData"
:excludeURLs="[
'/demo-blog/december',
'/demo-blog/november',
]"
/>Debug Format
The output for this format is messy and so it has been hidden in the dropdown:
Debug Format
[
{
"frontmatter": {
"aside": false,
"title": "October",
"subtitle": "Hiking Through Golden Forests",
"summary": "October transforms the world into a painter's masterpiece with golden forests and crisp hiking weather. Discover the magic of autumn trails where every step crunches through fallen leaves and every view takes your breath away.",
"date": "2025-10-31T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": false,
"category": "Fall",
"tags": [
"Hiking",
"Golden Forests",
"Fall Foliage",
"Nature",
"Trails"
],
"featured_image": {
"image": "/demo-blog/october-light.jpg",
"image_dark": "/demo-blog/october-dark.jpg",
"alt": "A path through autumn foliage, next to a blue-green lake",
"alt_dark": "A path through a forest with lots of leaves on the ground",
"description": "A path through autumn foliage, next to a blue-green lake - Credits to Hasmik Ghazaryan Olson on Unsplash",
"description_dark": "A path through a forest with lots of leaves on the ground - Credits to Irina Iriser on Unsplash"
},
"reading_time": 7,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "October - Hiking Through Golden Forests"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/october"
}
],
[
"meta",
{
"property": "og:description",
"content": "October transforms forests into golden masterpieces perfect for breathtaking hiking adventures."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/october-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/october"
},
{
"frontmatter": {
"aside": false,
"title": "September",
"subtitle": "Apple Picking and Harvest Adventures",
"summary": "September signals the start of harvest season with apple orchards heavy with fruit and crisp air that whispers of autumn's approach. Experience the joy of gathering nature's bounty and celebrating the changing seasons.",
"date": "2025-09-15T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": true,
"category": "Fall",
"tags": [
"Apple Picking",
"Harvest",
"Orchards",
"Autumn",
"Seasonal"
],
"featured_image": {
"image": "/demo-blog/september-light.jpg",
"image_dark": "/demo-blog/september-dark.jpg",
"alt": "A bunch of apples on the ground in the fall",
"alt_dark": "A tree filled with lots of green and red apples",
"description": "A bunch of apples on the ground in the fall - Credits to Anna Zakharova on Unsplash",
"description_dark": "A tree filled with lots of green and red apples - Credits to Gary Fultz on Unsplash"
},
"reading_time": 6,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "September - Apple Picking and Harvest Adventures"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/september"
}
],
[
"meta",
{
"property": "og:description",
"content": "September signals harvest season with apple picking adventures and autumn's first whispers."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/september-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/september"
},
{
"frontmatter": {
"aside": false,
"title": "August",
"subtitle": "Board Game Tournaments Indoors",
"summary": "August heat drives us indoors for epic board game marathons with friends and family. Discover the joy of strategic thinking, friendly competition, and air-conditioned comfort during the hottest days of summer.",
"date": "2025-08-12T00:00:00.000Z",
"author": "alex",
"status": "published",
"featured": false,
"category": "Summer",
"tags": [
"Board Games",
"Tournament",
"Indoor Activities",
"Strategy",
"Competition"
],
"featured_image": {
"image": "/demo-blog/august-light.jpg",
"image_dark": "/demo-blog/august-dark.jpg",
"alt": "A shelf with board games",
"alt_dark": "Board game pieces scattered on a road at night",
"description": "A shelf with board games - Credits to Madeline Liu on Unsplash",
"description_dark": "Board game pieces scattered on a road at night - Credits to Sølve on Unsplash"
},
"reading_time": 5,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "August - Board Game Tournaments Indoors"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/august"
}
],
[
"meta",
{
"property": "og:description",
"content": "August heat drives us indoors for epic board game tournaments and strategic fun."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/august-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/august"
},
{
"frontmatter": {
"aside": false,
"title": "July",
"subtitle": "Camping Under the Stars",
"summary": "July nights are made for camping adventures under star-filled skies. Experience the magic of sleeping under the open heavens, gathering around campfires, and disconnecting from the digital world to reconnect with nature.",
"date": "2025-07-04T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": false,
"category": "Summer",
"tags": [
"Camping",
"Stars",
"Campfire",
"Nature",
"Adventure"
],
"featured_image": {
"image": "/demo-blog/july-light.jpg",
"image_dark": "/demo-blog/july-dark.jpg",
"alt": "White tent on green grass field under white clouds during daytime",
"alt_dark": "A couple of tents sitting in the middle of a forest",
"description": "White tent on green grass field under white clouds during daytime - Credits to Kyle Johnson on Unsplash",
"description_dark": "A couple of tents sitting in the middle of a forest - Credits to Fajar Magsyar on Unsplash"
},
"reading_time": 7,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "July - Camping Under the Stars"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/july"
}
],
[
"meta",
{
"property": "og:description",
"content": "July nights are made for camping adventures under star-filled skies and magical campfire moments."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/july-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/july"
},
{
"frontmatter": {
"aside": false,
"title": "June",
"subtitle": "Beach Days and Sunrise Swimming",
"summary": "June ushers in summer with long days perfect for beach adventures and early morning swims. Embrace the freedom of warm weather, sandy toes, and the refreshing embrace of cool water under endless blue skies.",
"date": "2025-06-21T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": true,
"category": "Summer",
"tags": [
"Beach",
"Swimming",
"Sunrise",
"Water",
"Summer"
],
"featured_image": {
"image": "/demo-blog/june-light.jpg",
"image_dark": "/demo-blog/june-dark.jpg",
"alt": "Five birds flying on the sea",
"alt_dark": "A couple standing by the water at dusk",
"description": "Five birds flying on the sea - Credits to frank mckenna on Unsplash",
"description_dark": "A couple standing by the water at dusk - Credits to Olegs Jonins on Unsplash"
},
"reading_time": 6,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "June - Beach Days and Sunrise Swimming"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/june"
}
],
[
"meta",
{
"property": "og:description",
"content": "June ushers in summer with perfect beach days and refreshing sunrise swimming adventures."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/june-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/june"
},
{
"frontmatter": {
"aside": false,
"title": "May",
"subtitle": "Outdoor Picnics and Nature Walks",
"summary": "May beckons us outdoors with perfect weather for picnics in blooming meadows and leisurely nature walks. Experience the joy of dining al fresco and connecting with the natural world as spring reaches its peak.",
"date": "2025-05-18T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": false,
"category": "Spring",
"tags": [
"Picnics",
"Nature Walks",
"Outdoors",
"Blooming",
"Al Fresco"
],
"featured_image": {
"image": "/demo-blog/may-light.jpg",
"image_dark": "/demo-blog/may-dark.jpg",
"alt": "Green trees under sunny sky",
"alt_dark": "Empty brown wooden bench",
"description": "Green trees under sunny sky - Credits to Matthew Rumph on Unsplash",
"description_dark": "Empty brown wooden bench - Credits to kychan on Unsplash"
},
"reading_time": 6,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "May - Outdoor Picnics and Nature Walks"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/may"
}
],
[
"meta",
{
"property": "og:description",
"content": "May beckons us outdoors with perfect weather for picnics and nature walks in blooming landscapes."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/may-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/may"
},
{
"frontmatter": {
"aside": false,
"title": "April",
"subtitle": "Spring Cleaning and Fresh Air",
"summary": "April brings the irresistible urge to throw open windows, clear out clutter, and breathe new life into our living spaces. Discover the therapeutic joy of spring cleaning and the energy that comes with fresh beginnings.",
"date": "2025-04-10T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": false,
"category": "Spring",
"tags": [
"Spring Cleaning",
"Fresh Air",
"Organization",
"Renewal",
"Energy"
],
"featured_image": {
"image": "/demo-blog/april-light.jpg",
"image_dark": "/demo-blog/april-dark.jpg",
"alt": "A branch with cherry blossoms",
"alt_dark": "A path at night with cherry blossoms",
"description": "A branch with cherry blossoms - Credits to Redd Francisco on Unsplash",
"description_dark": "A path at night with cherry blossoms - Credits to ayumi kubo on Unsplash"
},
"reading_time": 5,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "April - Spring Cleaning and Fresh Air"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/april"
}
],
[
"meta",
{
"property": "og:description",
"content": "April brings the irresistible urge to spring clean and breathe new life into our spaces."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/april-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/april"
},
{
"frontmatter": {
"aside": false,
"title": "March",
"subtitle": "First Garden Planning and Seed Starting",
"summary": "March awakens the gardener's spirit as winter loosens its grip. It's time to plan your garden, start seeds indoors, and prepare for the growing season ahead. Feel the excitement of new growth and fresh possibilities.",
"date": "2025-03-20T00:00:00.000Z",
"author": "maya",
"status": "published",
"featured": true,
"category": "Spring",
"tags": [
"Gardening",
"Seeds",
"Planning",
"Growth",
"Outdoors"
],
"featured_image": {
"image": "/demo-blog/march-light.jpg",
"image_dark": "/demo-blog/march-dark.jpg",
"alt": "A close-up of some plants",
"alt_dark": "Purple flowers along a stone path, illuminated by small lights",
"description": "A close-up of some plants - Credits to Tebogo Sweatz on Unsplash",
"description_dark": "Purple flowers along a stone path, illuminated by small lights - Credits to Cee on Unsplash"
},
"reading_time": 7,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "March - First Garden Planning and Seed Starting"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/march"
}
],
[
"meta",
{
"property": "og:description",
"content": "March awakens the gardener's spirit with garden planning and seed starting for the season ahead."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/march-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/march"
},
{
"frontmatter": {
"aside": false,
"title": "February",
"subtitle": "Warm Baking and Hot Chocolate",
"summary": "February brings the heart of winter indoors with the comfort of baking fresh bread, creating sweet treats, and savoring steaming cups of hot chocolate. Discover the joy of kitchen warmth during the coldest month.",
"date": "2025-02-14T00:00:00.000Z",
"author": "alex",
"status": "published",
"featured": false,
"category": "Winter",
"tags": [
"Baking",
"Hot Chocolate",
"Kitchen",
"Comfort Food",
"Warmth"
],
"featured_image": {
"image": "/demo-blog/february-light.jpg",
"image_dark": "/demo-blog/february-dark.jpg",
"alt": "A cup of hot chocolate on a saucer, sitting on a white sheet",
"alt_dark": "A close-up of a cup of hot chocolate with marshmallows",
"description": "A cup of hot chocolate on a saucer, sitting on a white sheet - Credits to Laura Chouette on Unsplash",
"description_dark": "A close-up of a cup of hot chocolate with marshmallows - Credits to Sierra NiCole Narvaeth on Unsplash"
},
"reading_time": 6,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "February - Warm Baking and Hot Chocolate"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/february"
}
],
[
"meta",
{
"property": "og:description",
"content": "February brings the heart of winter indoors with comfort baking and steaming hot chocolate."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/february-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/february"
},
{
"frontmatter": {
"aside": false,
"title": "January",
"subtitle": "Cozy Reading by the Fireplace",
"summary": "Embrace the warmth of indoor activities as winter settles in. January offers the perfect opportunity to curl up with a good book, start new creative projects, and enjoy the peaceful quiet that comes with the coldest month of the year.",
"date": "2025-01-15T00:00:00.000Z",
"author": "alex",
"status": "published",
"featured": true,
"category": "Winter",
"tags": [
"Reading",
"Fireplace",
"Cozy",
"Indoor Activities",
"Books"
],
"featured_image": {
"image": "/demo-blog/january-light.jpg",
"image_dark": "/demo-blog/january-dark.jpg",
"alt": "A cup of coffee and a crocheted coaster next to an open book",
"alt_dark": "An open book near a mug, with a fireplace in the background",
"description": "A cup of coffee and a crocheted coaster next to an open book - Credits to Céline Druguet on Unsplash",
"description_dark": "An open book near a mug, with a fireplace in the background - Credits to Pavan Trikutam on Unsplash"
},
"reading_time": 5,
"head": [
[
"meta",
{
"property": "og:type",
"content": "blog"
}
],
[
"meta",
{
"property": "og:locale",
"content": "en_CA"
}
],
[
"meta",
{
"property": "og:title",
"content": "January - Cozy Reading by the Fireplace"
}
],
[
"meta",
{
"property": "og:url",
"content": "https://vitepress-valence.cynber.dev/demo-blog/january"
}
],
[
"meta",
{
"property": "og:description",
"content": "Embrace the warmth of indoor activities as winter settles in with cozy reading and creative projects."
}
],
[
"meta",
{
"property": "og:image",
"content": "https://vitepress-valence.cynber.dev/demo-blog/january-dark.jpg"
}
],
[
"meta",
{
"property": "article:section",
"content": "Seasonal"
}
]
]
},
"url": "/demo-blog/january"
}
]The following code was used:
vue
<VpvArticleList
format="debug"
postsDataKey="demoBlogData"
:excludeURLs="[
'/demo-blog/december',
'/demo-blog/november',
]"
/>