Function useMetadataQuery

Query the file metadata store (MDX frontmatter) with a plain JS function.

The query receives every file's frontmatter keyed by path and returns the paths that match; the hook resolves each path back to its frontmatter and returns an array of { path, meta } entries — so a single call gives you everything you filtered on, with no second lookup. A throwing query is reported as { error } rather than crashing the render.

The query runs synchronously during render (no empty first frame), and the returned array keeps its identity while the matches are unchanged, so it is safe to use directly in downstream useMemo/useEffect dependency arrays.

A query may return RECORDS instead of bare paths (R3-276) — { path, ...extra } — and the extra fields ride along on each entry, so something derived while selecting does not have to be recomputed downstream:

const posts = useMetadataQuery<PostMeta, { year: string }>((files) =>
  Object.entries(files).map(([path, m]) => ({ path, year: m.date.slice(0, 4) })),
);
Copy

The store it queries is the nearest MetadataSource, else the host's.

Pass a type parameter to get typed frontmatter throughout:

interface PostMeta { title: string; date: string; draft?: boolean }
const posts = useMetadataQuery<PostMeta>((files) =>
  Object.entries(files)
    .filter(([, m]) => !m.draft)
    .sort(([, a], [, b]) => b.date.localeCompare(a.date))
    .map(([path]) => path),
);
Copy