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