@likec4/diagram NPM

`@likec4/diagram`

A React component library for rendering software architecture diagrams.\ Although you can use them directly, it is recommended to use likec4 CLI to generate components from LikeC4 sources.

Install:

pnpm add @likec4/diagram

See:

Docs - https://likec4.dev/tooling/react/
Demo - https://template.likec4.dev/

Contents:

Bundled version

The easiest way to use this package is the bundled version.\ Diagram renders inside shadow DOM and has its own styles.

LikeC4View

import { LikeC4Model } from '@likec4/core/model'
import { LikeC4ModelProvider, LikeC4View } from '@likec4/diagram/bundle'

// instance of LikeC4Model
// See https://likec4.dev/tooling/model-api/
const likec4model = LikeC4Model.fromDump()

function App() {
  return (
    <LikeC4ModelProvider model={likec4model}>
      <LikeC4View
        viewId="index1"
        onNodeClick={(nodeId) => console.log(nodeId)}
      />

      <LikeC4View viewId="index2" />
    </LikeC4ModelProvider>
  )
}

See LikeC4ViewProps for available props.

You may need to import icons, if you use built-in node renderers.

import { type ElementIconRenderer, LikeC4, LikeC4ModelProvider, LikeC4View } from '@likec4/diagram/bundle'
import { lazy, Suspense } from 'react'

// Better to lazy load icons, bundle is quite large at the moment
const Icon = lazy(() => import('@likec4/icons/all').then((m) => ({ default: m.IconRenderer })))

const IconRenderer: ElementIconRenderer = (props) => {
  return (
    <Suspense>
      <Icon {...props} />
    </Suspense>
  )
}

function App() {
  return (
    <LikeC4ModelProvider model={likec4model}>
      <LikeC4View
        viewId="index1"
        renderIcon={IconRenderer}
      />
    </LikeC4ModelProvider>
  )
}

ReactLikeC4

LikeC4View renders views from your model, and allows exploring in the popup browser. Component works in most usecases, but if you need more - use ReactLikeC4:

import { ReactLikeC4, LikeC4ModelProvider } from '@likec4/diagram/bundle'

function App() {
  const [viewId, setViewId] = useState('index')
  return (
    <LikeC4ModelProvider model={likec4model}>
      <ReactLikeC4
        viewId={viewId}
        pannable
        zoomable={false}
        keepAspectRatio
        showNavigationButtons
        enableDynamicViewWalkthrough={false}
        enableElementDetails
        enableRelationshipDetails
        showDiagramTitle={false}
        onNavigateTo={setViewId}
        onNodeClick={...}
      />
    </LikeC4ModelProvider>
  )
}

`likec4/react`

Package likec4/react re-exports everything from Bundled version.\ It also re-exports likec4/icons/all.

Library version

If you want to use package as a library, you have to install dependencies and prepare CSS.

Library uses Mantine. If you already use it and have MantineProvider on the scope - LikeC4Diagram will use it. Otherwise, it will wrap itself with MantineProvider.

Even if you are not planning to use Mantine in your app, its styles are required for the diagrams to work (don't worry, Mantine is tree-shakable).

Here are the options:

With bundled styles

Complete styles
```
@import '@likec4/diagram/styles.css'
```
This includes all styles, including Mantine styles.

If you are using Mantine

@layer reset, base, mantine, xyflow, tokens, recipes, utilities;
@import "@mantine/core/styles.layer.css";
@import "@likec4/diagram/styles-min.css";

!IMPORTANT Layers order is important.

Font.\ LikeC4Diagram uses IBM Plex Sans by default.\ You can import it from fontsource or any other CDN, bundle, or import:
```
@import '@likec4/diagram/styles-font.css'
```
!NOTE This stylesheet loads font from FontSource

With PandaCSS

pnpm add @likec4/styles

Configure your panda.config.ts:

import likec4preset from '@likec4/styles/preset'
import { defineConfig } from '@pandacss/dev'

export default defineConfig({
  include: [
    'src/**/*.{ts,tsx}',
    // Include likec4 diagram source code to get the styles
    './node_modules/@likec4/diagram/panda.buildinfo.json',
  ],
  importMap: [
    '@likec4/styles',
  ],
  presets: [
    likec4preset,
  ],
  theme: {
    extend: {
      // Here you can override/extend the theme
    },
  },
})

You global CSS should look like this:

@layer reset, base, mantine, xyflow, tokens, recipes, utilities;
@import "@mantine/core/styles.layer.css";
@import "@likec4/diagram/styles-xyflow.css";
@import "@likec4/diagram/styles-font.css";

Check PandaCSS docs for full setup instructions.

Usage

Same as ReactLikeC4, but import from @likec4/diagram:

import { LikeC4Diagram } from '@likec4/diagram'

function App() {
  const [viewId, setViewId] = useState('index')
  // Get instance of view
  const view = likec4model.view(viewId).$view
  return (
    <LikeC4Diagram
      view={view} 
      pannable
      zoomable={false}
      keepAspectRatio
      showNavigationButtons
      enableDynamicViewWalkthrough={false}
      enableElementDetails
      enableRelationshipDetails
      showDiagramTitle={false}
      onNavigateTo={setViewId}
      onNodeClick={...}
    />
  )
}

You can render any component inside LikeC4Diagram:

import { LikeC4Diagram, LikeC4ModelProvider } from '@likec4/diagram'
import { Panel, ViewportPortal } from '@xyflow/react'

function App() {
  return (
    <LikeC4Diagram>
      <YourComponent />

      {/* You can use components from xyflow  */}
      <Panel position="top">
        <p>Your component as a panel</p>
        <a href="https://reactflow.dev/examples">Check examples</a>
      </Panel>

      <ViewportPortal>
        <div
          style={{
            transform: 'translate(100px, 100px)',
            position: 'absolute',
          }}>
          This div is positioned at [100, 100] on the diagram canvas
        </div>
      </ViewportPortal>
    </LikeC4Diagram>
  )
}

Customization

Custom node renderer

LikeC4Diagram can use custom node renderers.\ Compose custom nodes renderers using primitives from @likec4/diagram/custom (or @likec4/diagram/bundle/custom for the bundled version).\ See customNodes.tsx for examples.

import { LikeC4Diagram } from '@likec4/diagram'
import {
  ElementActions,
  ElementDetailsButtonWithHandler,
  elementNode,
  ElementNodeContainer,
  ElementShape,
  ElementTitle,
  ElementToolbar,
  IfNotReadOnly,
} from '@likec4/diagram/custom'
import { IconPlus } from '@tabler/icons-react'

const renderNodes = {
  element: elementNode(({ nodeProps, nodeModel }) => (
    <ElementNodeContainer nodeProps={nodeProps}>
      <ElementShape {...nodeProps} />
      <ElementTitle {...nodeProps} />
      <ElementActions
        {...nodeProps}
        extraButtons={[
          {
            key: 'plus',
            icon: <IconPlus />,
            onClick: () => console.log('extra'),
          },
        ]}
      />
      <div style={{ position: 'absolute', bottom: 0 }}>
        {nodeModel.element.getMetadata('your-attr')}
      </div>
    </ElementNodeContainer>
  )),
}

function App() {
  return (
    <LikeC4Diagram
      view={view}
      renderNodes={renderNodes}
    />
  )
}