Knowledge base

LibraryPage is the default Chakra surface for a knowledge base. It owns the complete document workflow; DocumentItem and DocumentProgress are the smaller presentation pieces for a custom library view.

Usage

HyperflowApp registers the library page at /library. To place it in a custom Chakra route, render LibraryPage inside the Hyperflow application boundary:

import { LibraryPage } from '@hyperflow/chakra-ui'

export function DocumentsPage() {
  return <LibraryPage />
}

It loads collections, documents, search results, uploads, retries, and deletions through useKnowledgeBaseLibrary.

Examples

Build a custom document list

Use the headless library contract with DocumentItem when the application needs a different page layout but should retain the default document cards, actions, and progress feedback.

src/components/project-library.tsx

import { Stack } from '@chakra-ui/react'
import { DocumentItem } from '@hyperflow/chakra-ui'
import { useKnowledgeBaseLibrary } from '@hyperflow/react'

export function ProjectLibrary() {
  const library = useKnowledgeBaseLibrary()

  return (
    <Stack gap="2">
      {library.documents.map((document) => (
        <DocumentItem
          key={document.filename}
          document={document}
          view="list"
          onDelete={() => library.deleteFile(document.filename)}
          onRetry={() => library.retryUpload(document.filename)}
        />
      ))}
    </Stack>
  )
}

Guide

Keep library state in the headless contract

LibraryPage gets collections, documents, searching, upload progress, retries, and deletions from useKnowledgeBaseLibrary. A custom page should use that hook instead of recreating a separate knowledge-base state or calling the client directly.

Choose the smallest surface

Use LibraryPage for the complete route. Use DocumentItem when only a document row or card needs the default visual treatment. Use DocumentProgress when a custom item needs the default upload and indexing indicator.

Preserve document actions

DocumentItem needs onDelete and onRetry callbacks because the enclosing page owns the document collection. Forward them to deleteFile and retryUpload from useKnowledgeBaseLibrary so the visual action and the active collection stay in sync.

For a complete headless walkthrough, see Add a knowledge base surface.

Props

LibraryPage

Prop	Default	Type
—	—	— No props.

DocumentItem

Prop	Default	Type
`document`	—	`KnowledgeBaseDocument` Required. The document to render.
`view`	—	`"grid" \| "list"` Required. Chooses the card or row presentation.
`onDelete`	—	`(document: KnowledgeBaseDocument) => void` Required. Deletes the selected document.
`onRetry`	—	`(document: KnowledgeBaseDocument) => void` Required. Retries a failed upload or refreshes its indexing state.
`snippet`	—	`string` Optional search-result excerpt shown instead of the document status.
`labels`	Built-in Italian labels	`DocumentItemLabels` Overrides visible status and action copy.
`progressLabels`	Built-in Italian labels	`DocumentProgressLabels` Overrides accessible upload and indexing copy.

DocumentProgress

Prop	Default	Type
`document`	—	`KnowledgeBaseDocument` Required. Supplies the upload or indexing status and percentage.
`view`	—	`"grid" \| "list"` Required. Matches the surrounding document presentation.
`labels`	Built-in Italian labels	`DocumentProgressLabels` Overrides accessible progress copy.

For the complete types, see the @hyperflow/chakra-ui reference.

On this page