Styling

ngDiagram provides a default well-structured design system with a clear separation of concerns. Its styling is based on a minimal yet sufficient set of primitives, tokens, and component-level variables that support consistent theming and easy customization across all library components.

In addition to the design system, the library includes components, directives, and CSS classes to help you build consistent and interactive diagram interfaces.

Design System Architecture

The styling system consists of three distinct layers:

Primitives

Base color values and fundamental design tokens defined in primitives. These are the foundation colors that power the entire design system:

1
:root {
2
  --ngd-colors-gray-100: /* white */;
3
  --ngd-colors-gray-300: /* light gray */;
4
  --ngd-colors-gray-400: /* medium light gray */;
5
  --ngd-colors-gray-500: /* medium gray */;
6
  --ngd-colors-gray-600: /* medium dark gray */;
7
  --ngd-colors-gray-650: /* dark gray */;
8
  --ngd-colors-gray-700: /* darker gray */;
9
  --ngd-colors-gray-800: /* darkest gray */;
10
  --ngd-colors-acc1-400: /* primary accent light */;
11
  --ngd-colors-acc1-500: /* primary accent */;
12
  --ngd-colors-acc1-500-40: /* primary accent with 40% opacity */;
13
  --ngd-colors-acc1-500-50: /* primary accent with 50% opacity */;
14
  --ngd-colors-acc4-500: /* secondary accent */;
15
}

Note: The actual color values are defined in the library. Override these variables to customize the color palette for your design system.

Tokens

Semantic design tokens that map primitives to specific use cases, supporting themes:

1
:root {
2
  --ngd-node-bg-primary-default: var(--ngd-colors-gray-100);
3
  --ngd-node-stroke-primary-default: var(--ngd-colors-gray-400);
4
  --ngd-node-stroke-primary-hover: var(--ngd-colors-acc1-500);
5
  /* ... more tokens */
6
}
7

8
html[data-theme='dark'] {
9
  --ngd-node-bg-primary-default: var(--ngd-colors-gray-700);
10
  --ngd-node-stroke-primary-default: var(--ngd-colors-gray-600);
11
  --ngd-node-stroke-primary-hover: var(--ngd-colors-acc1-400);
12
  /* ... more tokens */
13
}

Component Variables

Component-specific CSS variables that use tokens for consistent styling:

1
:root {
2
  --ngd-node-background-color: var(--ngd-node-bg-primary-default);
3
  --ngd-node-border-color: var(--ngd-node-stroke-primary-default);
4
  --ngd-node-border-color-hover: var(--ngd-node-stroke-primary-hover);
5
  /* ... more component variables */
6
}

Theming

Default Themes

ngDiagram supports both light and dark themes out of the box by default:

Light theme - Applied by default (no HTML attribute needed)
Dark theme - Applied when data-theme="dark" is set on the html element

1
<!-- Dark theme (optional) -->
2
<html data-theme="dark">
3
  <!-- Dark theme is applied -->
4
</html>

Customization

Note: The following customization options are optional.

Global Color Override

To quickly adapt to your design system, override primitives:

1
:root {
2
  --ngd-colors-acc1-500: #your-primary-color;
3
  --ngd-colors-gray-500: #your-gray-color;
4
  /* Override other primitives as needed */
5
}

Component-Specific Customization

For precise control, override component variables:

1
:root {
2
  --ngd-node-border-radius: 0.5rem;
3
  --ngd-node-border-size: 0.125rem;
4
  --ngd-group-border-radius: 1rem;
5
  /* Customize specific component properties */
6
}

Utility Classes

Port Highlighting Classes

`.ng-diagram-port-hoverable-over-node`

Applied to node containers. When the cursor hovers over the node, all ports are highlighted with the default node styling.

`.ng-diagram-port-hoverable`

Applied to node containers as well. The port is highlighted only when the cursor hovers directly over it.

1
<!-- Node with hoverable ports -->
2
<div class="ng-diagram-port-hoverable-over-node">
3
  <!-- Node content -->
4
  <ng-diagram-port id="port-left" type="both" side="left" />
5
  <ng-diagram-port id="port-right" type="both" side="right" />
6
</div>
7

8
<!-- Individual hoverable port -->
9
<div class="ng-diagram-port-hoverable">
10
  <!-- Node content -->
11
  <ng-diagram-port id="port-left" type="both" side="left" />
12
  <ng-diagram-port id="port-right" type="both" side="right" />
13
</div>

Directives

Note: Directives require access to node/group data. When used outside of node templates, they won’t work. For manual control, use CSS classes instead.

NgDiagramNodeSelectedDirective

Automatically adds selection styling based on the node’s selected property:

1
<div ngDiagramNodeSelected [node]="node">
2
  <!-- Node content -->
3
</div>

Applied styling:

Adds ng-diagram-node-selected class when selected is true
Provides focus ring and outline styling
Works for both nodes and groups

NgDiagramGroupHighlightedDirective

Adds highlight styling to groups based on the highlighted property:

1
<div ngDiagramGroupHighlighted [node]="node">
2
  <!-- Group content -->
3
</div>

Applied styling:

Adds ng-diagram-group-highlight class when highlighted is true
Provides inner outline and background highlight
Indicates when dragging elements can be added to the group

Manual CSS Classes

For cases where directives can’t be used (outside node templates), you can apply styling manually:

ng-diagram-node-selected
ng-diagram-group-highlight

1
<!-- Selection styling -->
2
<div class="ng-diagram-node-wrapper ng-diagram-node-selected">
3
  <!-- Node content -->
4
</div>
5

6
<!-- Group highlight styling -->
7
<div class="ng-diagram-node-wrapper ng-diagram-group-highlight">
8
  <!-- Group content -->
9
</div>

Best Practices

Use primitives for global color changes - Override --ngd-colors-* variables for brand consistency
Use component variables for specific adjustments - Override --ngd-* variables for precise control
Leverage utility classes - Use provided classes for consistent behavior
Use directives for visual state management - Let directives handle selection and highlight states
Maintain layer separation - Use component variables instead of applying primitives or tokens directly within components.