Data Dictionary Viewer

Data Dictionary Viewer is a customizable component for visualizing data dictionaries. It supports list and table views, includes built-in search, and offers modern, responsive styling. Easy to embed, easy to style.

Features

🔍 Searchable: Filter variable names and descriptions

🧱 Two Views: Toggle between List and Table formats

🎨 Theme Support: Light and dark themes with CSS variable overrides

🔌 Plug & Play: Easy to integrate in any React app or use as a standalone Web Component

⚡ Fast Parsing: Parses CSV data

Project overview

• React: v18.2.0
• Node.js: v22.16.0
• NPM: v10.9.2

Built with React, the Data Dictionary Viewer is available as:

• React Component (via NPM)
• Web Component (framework-agnostic)

🚀 Live demo: https://bmir-radx.github.io/data-dictionary-viewer-component/

Input data

Data dictionaries are expected to follow these specifications. The input data can be provided as:

• CSV file
• Raw string
• URL to API endpoint

Dependencies

• Font Awesome
• Papa Parse
• react-tooltip
• react-virtuoso

React Component

Installation

$ npm install @cyouh95/data-dictionary-viewer

Usage

Import the DataDictionaryViewer component and CSS file in your React project:

import { DataDictionaryViewer } from '@cyouh95/data-dictionary-viewer'
import '@cyouh95/data-dictionary-viewer/style.css'

Use component as:

<DataDictionaryViewer data="data_dictionary_file.csv" />

Full list of props:

Prop Name	Type	Default	Options	Description
data	string	—	required	Path to the CSV data dictionary file OR string containing the data OR URL to API endpoint.
initialView	string	'list'	'list', 'table'	Set the default view mode when component loads.
showSearch	boolean	true	true, false	Toggle visibility of the search bar.
heading	string	'Data Dictionary Viewer'	Any string	Custom title displayed at the top.
theme	string	'light'	'light', 'dark'	Choose between different visual themes.

Customization

Customize styles by overriding CSS variables:

:root {
    --dd-color-primary: #bb86fc;
    ...
}

If using a theme other than the default light theme, override CSS variables using corresponding theme class selector:

.dark {
    --dd-color-primary: #bb86fc;
    ...
}

See full list of CSS variables below.

Web Component

Import data-dictionary-viewer.js in your HTML file:

<script type="module" src="data-dictionary-viewer.js"></script>

Use component as:

<data-dictionary-viewer data="data_dictionary_file.csv"></data-dictionary-viewer>

Full list of attributes:

Attribute Name	Type	Default	Options	Description
data	string	—	required	Path to the CSV data dictionary file OR string containing the data OR URL to API endpoint.
initial-view	string	'list'	'list', 'table'	Set the default view mode when component loads.
show-search	string	'true'	'true', 'false'	Toggle visibility of the search bar.
heading	string	'Data Dictionary Viewer'	Any string	Custom title displayed at the top.
theme	string	'light'	'light', 'dark'	Choose between different visual themes.

Customization

Customize styles by overriding CSS variables:

data-dictionary-viewer {
    --dd-color-primary: #bb86fc;
    ...
}

If using a theme other than the default light theme, override CSS variables using corresponding theme class selector:

data-dictionary-viewer .dark {
    --dd-color-primary: #bb86fc;
    ...
}

See full list of CSS variables below.

CSS variable reference

CSS Variable	Description
--dd-font-family	Default font stack
--dd-color-text	Color of text
--dd-color-body-bg	Background color of overall page body
--dd-color-primary	Primary accent color used for buttons and icon
--dd-color-on-primary	Text/icon color when placed on --dd-color-primary
--dd-color-secondary	Secondary accent color used for table header background
--dd-color-on-secondary	Text/icon color when placed on --dd-color-secondary
--dd-color-content-bg	Background color of content areas
--dd-color-content-border	Border color around content areas
--dd-color-card-bg	Background color of cards
--dd-color-card-border	Border color around cards
--dd-color-card-block-bg	Background color of inner card blocks
--dd-color-card-block-border	Border color around inner card blocks
--dd-color-button-text	Color of text inside buttons
--dd-color-button-bg	Background color of buttons
--dd-color-button-bg-hover	Background color of buttons on hover
--dd-color-button-border	Border color around buttons
--dd-color-table-border	Border color around tables
--dd-color-table-odd	Background color of odd table rows
--dd-color-table-even	Background color of even table rows
--dd-color-input-bg	Background color of input fields
--dd-color-input-border	Border color around input fields
--dd-color-tooltip-background	Background color of tooltips
--dd-color-filter	Color of filter icons in table view
--dd-shadow	Box shadow used for elements such as buttons

Set up locally

Clone the repository:

$ git clone https://github.com/bmir-radx/data-dictionary-viewer-component.git
$ cd data-dictionary-viewer-component

Install packages:

$ npm install

Run locally:

$ npm run dev

See: index.html, main.jsx

Deploy to GitHub Pages

$ npm run deploy

This will run the predeploy and deploy scripts defined in package.json:

"scripts": {
    "predeploy": "vite build --config vite.config.gh.js",
    "deploy": "gh-pages -d build"
}

Or, set up GitHub Actions as seen in deploy.yml.

See: index.html, main.jsx, vite.config.gh.js (outputs to build/ folder)

👉 View demo GitHub Pages site

Publish to NPM

$ npm run build

This will run the build script defined in package.json:

"scripts": {
    "build": "vite build"
}

Increment version of package:

# Use one of the following based on changes made:
$ npm version patch
$ npm version minor
$ npm version major

Publish to NPM registry:

$ npm publish --access public

See: index.ts, vite.config.ts (outputs to dist/ folder)

👉 View NPM package

Convert to Web Component

$ npm run convert

This will run the convert script defined in package.json:

"scripts": {
    "convert": "vite build --config vite.config.web.js"
}

See: web.jsx, vite.config.web.js (outputs to web/ folder)

👉 View Web Component file