@3dsource/source-ui
A comprehensive library of Angular UI components designed specifically for 3D visualization applications. This library extends Angular Material with specialized components for 3D content interaction.
Overview
The Source UI library provides Angular components that are optimized for 3D applications, offering:
- Specialized UI controls for 3D scene manipulation
- Integration with Angular Material design system
- Responsive and accessible components
- Consistent styling across 3D Source applications
Installation
Prerequisites
- Node.js 20 or newer for repository tooling
- Angular, Angular CDK and Angular Material
>=19.0.0 <23.0.0 - RxJS
>=7.8.0 <8.0.0 - @3dsource/source-ui-native -- required peer dependency; provides the base design tokens and styles that Source UI components rely on
Peer Dependencies
This library requires the following peer dependencies:
{
"@3dsource/source-ui-native": ">=2.0.0",
"@angular/cdk": ">=19.0.0 <23.0.0",
"@angular/common": ">=19.0.0 <23.0.0",
"@angular/core": ">=19.0.0 <23.0.0",
"@angular/forms": ">=19.0.0 <23.0.0",
"@angular/material": ">=19.0.0 <23.0.0",
"@angular/platform-browser": ">=19.0.0 <23.0.0",
"rxjs": ">=7.8.0 <8.0.0"
}
Swiper is not declared as a package dependency. Applications using the swiper mode of tabs must provide it themselves.
Library Installation
npm install @3dsource/source-ui @3dsource/source-ui-native
AI coding agents
The package ships documentation for coding agents (llms.txt, guides/,
docs/) that matches the installed version. To make the agents in your project
read it, add the block below to AGENTS.md in the project root. If the project
has a CLAUDE.md, also add the line @AGENTS.md to it: Claude Code reads
AGENTS.md on its own only when there is no CLAUDE.md.
## 3D Source UI libraries
This project uses `@3dsource/source-ui-native` and, when needed, `@3dsource/source-ui`. Their docs ship inside the packages and match the installed version. Before you write or change UI code that uses them, read the `llms.txt` of each installed package and follow its links (setup, rules, the API of each component you use):
- `node_modules/@3dsource/source-ui-native/llms.txt`
- `node_modules/@3dsource/source-ui/llms.txt`
Search tools usually skip `node_modules`, so open these files by path. The paths start from the folder of the `package.json` that lists `@3dsource/*`. In a monorepo this can be an app folder, not the repository root.
Do not guess component names, inputs or CSS classes. Use only what these files list.
Which package to install:
- By default, only `@3dsource/source-ui-native`.
- Add `@3dsource/source-ui` (always together with `@3dsource/source-ui-native`) only for: breadcrumbs, color picker, popover, slider group, tab line, tooltip, the CDK modal, styled Angular Material form fields, ngx-toastr toasts.
- `@3dsource/source-ui` needs Angular. In a project without Angular, use only the styles of `@3dsource/source-ui-native`. Its `llms.txt` explains how.
If the agent cannot read the files of your project (for example, an AI chat in the browser), give it the public copy of the docs on jsDelivr. Each link is one file with all the guides and the API of the package. For @3dsource/source-ui, give both links, because it works only together with @3dsource/source-ui-native.
- https://cdn.jsdelivr.net/npm/@3dsource/source-ui-native/docs/llms-full.txt
- https://cdn.jsdelivr.net/npm/@3dsource/source-ui/docs/llms-full.txt
The links show the latest release, and for up to 7 days after a new release they can still show the previous one. For the docs of a specific version, add it to the package name, for example @3dsource/source-ui-native@<version>.
Usage
Style imports
Import both style entrypoints in the application's global styles.scss:
// Source UI Native
@use '../node_modules/@3dsource/source-ui-native/styles/source.ui.native.scss' as source-ui-native;
// Source UI
@use '../node_modules/@3dsource/source-ui/styles/source.ui.scss' as source-ui;
Wrap the application (or the area that uses the design system) in the global scope class used by the tokens and typography:
<body class="section_3dsourcecom">
<app-root></app-root>
</body>
Material settings
For correct form styling, provide the outline appearance in the application configuration:
import { ApplicationConfig } from '@angular/core';
import { MAT_FORM_FIELD_DEFAULT_OPTIONS } from '@angular/material/form-field';
export const appConfig: ApplicationConfig = {
providers: [
{
provide: MAT_FORM_FIELD_DEFAULT_OPTIONS,
useValue: { appearance: 'outline' },
},
],
};
Import
Import desired component and use it in template as described in components documentation.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { SourceSliderGroupComponent } from '@3dsource/source-ui';
@Component({
selector: 'app-example',
imports: [SourceSliderGroupComponent],
template: ` <src-slider-group label="Slider Group" [min]="0" [max]="100" [step]="1" units="" [showRange]="true" [value]="value()" (groupValueChange)="onValueChange($event)" /> `,
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ExampleComponent {
value = signal(15);
onValueChange(value: number) {
this.value.set(value);
}
}
Available Components and Examples
- src-breadcrumbs - Template-driven breadcrumb navigation with overflow handling
- src-color-picker - Highly customizable colorpicker
- src-modal - Service modal component
- src-popover - Popover with trigger or Service
- src-slider-group - Advanced variant of slider
- src-tab-line - Compact tab-line control
- src-tabs - Tabs in two options of usage
- src-tooltip - Directive for custom tooltips
Customization
Customization provided in the same way as in SourceUI Native. Whole table of CSS custom properties is available in the documentation site.
You can see all available options and examples in documentation
Repository development
Run commands from the repository root:
pnpm source-ui:build
pnpm source-ui:release:patch
The release command performs verification, changes the package version and publishes the verified tarball to npm.