Directory Component

The Directory component creates structured, hierarchical navigation with collapsible sections. Perfect for documentation sites, file explorers, and nested navigation menus. Inspired by the Astro Starlight navigation component.

Key Features

• Hierarchical Display: Visualize complex content structures

• Collapsible Sections: Toggle visibility of nested items

• Active Item Tracking: Automatically highlights current selection

• Smooth Scrolling: Auto-scrolls to active items

• Badge Support: Add visual indicators to items

Basic Usage

1
<Directory
2
    directory={[{
3
        label: 'Getting Started',
4
        items: [
5
            { label: 'Installation', href: '/docs/installation' },
6
            { label: 'Configuration', href: '/docs/configuration' },
7
        ],
8
    }]}
9
    currentDocSlug="installation"
10
    collapsable={true}
11
/>

Depth Control

Limit the nesting depth of your directory structure:

1
<Directory directory={directoryData} maxDepth={3} Only show 3 levels of nesting />

Utilizing Content Collections

Below is an example of how to utilize the Directory component with the Astro content collections. You can see the example on the left side of the screen now, we use this component for our documentation navigation.

Layout File

1
---
2
import { type CollectionEntry } from 'astro:content';
3
import Directory from '@/components/NST-components/UI/directory/Directory.astro';
4
import { getCollection } from 'astro:content';
5

6
export interface Props {
7
  post?: CollectionEntry<'docs'>;
8
}
9

10
const { post } = Astro.props;
11
const { slug } = post || {};
12
const directory = await getCollection('docs');
13
---
14

15
<Directory
16
  collapsable
17
  currentDocSlug={slug || ''}
18
  baseUrl="/docs/"
19
  {directory}
20
/>

Content Collections Config

1
import { badgeStyleKeys } from '@/components/NST-components/UI/badge/styling';
2
import { defineCollection, z } from 'astro:content';
3

4
const docs = defineCollection({
5
  type: 'content',
6
  schema: () =>
7
    z.object({
8
      sidebar: z
9
        .object({
10
          label: z.string(),
11
          dropDownLabel: z.string().optional(),
12
          order: z.number().optional(),
13
          badge: z
14
            .object({
15
              text: z.string(),
16
              variant: z.enum(badgeStyleKeys),
17
            })
18
            .optional(),
19
        })
20
        .optional(),
21
    }),
22
});
23

24
export const collections = { docs };

Base URL

Set the base URL to the root of your content collection. This is used to generate the correct URLs for the directory items. If all your content collection starts at the path /docs/, you can set the base URL to /docs/.

Directory Component Props API

DirectoryItem Type

1
interface DirectoryItem {
2
  label: string;
3
  href?: string;
4
  items?: any[];
5
  badge?: {
6
    variant: BadgeStyleKeys;
7
    text: string;
8
  };
9
  dropDownLabel?: string;
10
  dropDownBadge?: {
11
    variant: BadgeStyleKeys;
12
    text: string;
13
  };
14
  collapsed?: boolean;
15
}

Best Practices

1. Structure Organization

   • Keep nesting depth reasonable (3-4 levels max)
   • Use clear, descriptive labels
   • Group related items logically
   • Consider alphabetical ordering

2. Visual Clarity

   • Use badges sparingly
   • Maintain consistent spacing
   • Ensure sufficient contrast
   • Consider mobile viewports

Common Use Cases