Adding an example to the Gallery

We welcome anyone to submit an example to our gallery.

Overview

Add your example to the directory packages/shared/examples. Before submitting a pull request, make sure you have done the following:

• Made a directory with all of the required files
• Updated the list of examples in examples-list.tsx to include yours
• Added light and dark screenshots of your example to the _previews directory as png files
• Verified the example works in each of our supported UI frameworks (how-to guide here)

Required Files

Your directory should be called your-example-name. In it, you will need to have files for all of our supported UI frameworks (angular, react, svelte, vue, solid and vanilla typescript) as well as a data and index file. The structure looks like:

your-example
├── data.ts
├── index.tsx
├── your-example.component.html # ┓
├── your-example.component.ts   # ┠ angular
├── your-example.module.ts      # ┛
├── your-example.svelte         # svelte
├── your-example.vue            # vue
├── your-example-solid.tsx      # solid
├── your-example.ts             # typescript (the vanilla TS entry — name it exactly your-example.ts)
├── your-example.tsx            # react

What to include in index.tsx

All example index files look roughly the same, you will just need to fill in the highlighted lines. You can copy and paste the following:

/* eslint-disable import/no-unresolved, import/no-webpack-loader-syntax, @typescript-eslint/no-var-requires */
import React from 'react'
import type { Example } from '../types'

const pathname = ''
const example: Example = {
  component: () => {
    // eslint-disable-next-line @typescript-eslint/naming-convention
    const Component = require(`./${pathname}.tsx`).default
    return <Component />
  },
  pathname,
  title: '',
  description: '',
  codeReact: require(`!!raw-loader!./${pathname}.tsx`).default,
  codeSolid: require(`!!raw-loader!./${pathname}-solid.tsx`).default,
  codeTs: require(`!!raw-loader!./${pathname}.ts`).default,
  codeAngular: {
    html: require(`!!raw-loader!./${pathname}.component.html`).default,
    component: require(`!!raw-loader!./${pathname}.component.ts`).default,
    module: require(`!!raw-loader!./${pathname}.module.ts`).default,
  },
  codeSvelte: require(`!!raw-loader!./${pathname}.svelte`).default,
  codeVue: require(`!!raw-loader!./${pathname}.vue`).default,
  data: require('!!raw-loader!./data').default,
  preview: require(`../_previews/${pathname}.png`).default,
  previewDark: require(`../_previews/${pathname}-dark.png`).default,
}

export default example

note

• pathname should correspond to your directory name
• title should reference the library component(s) you're using
• description should be a brief description of your visualization with any data sources cited

Testing each framework

Before you submit a pull request, be sure you have verified that the example works for each framework on your local machine.

Multi-framework playground (recommended)

From the repository root, run:

pnpm dev:gallery

Open the URL printed by Vite and pick your example in the sidebar. It renders the React, Vue, Solid, Svelte and vanilla TypeScript variants side by side. Examples are discovered automatically from packages/shared/examples/* — there is no manual registration step. The TypeScript panel only mounts a file named exactly your-example.ts (data.ts and types.ts are treated as shared helpers, not entry points). Angular is not part of this playground — preview it on the website or with the Angular gallery below.

Website

From the repository root, run pnpm website and open localhost:9300. Navigate to your example's page to see it rendered together with the code listing for every framework. To preview the vanilla TypeScript render, append &ts to the example URL.

Angular

Angular isn't included in the multi-framework playground, so preview it with its own gallery:

1. Import your angular module in gallery/src/main.ts
2. Add the imported module to the imports field in the NgModule decorator:

@NgModule({
declarations: [AppComponent],
imports: [... /* your angular module here */],
bootstrap: [AppComponent],
providers: [BrowserModule],
})

3. Add the example component's selector to the Component decorator's template field:

@Component({
  selector: 'app-component',
  template: `
    ...
    <!-- your angular selector -->
  `
})

4. From the terminal, run the command

cd packages/angular
pnpm gallery