Demos

A demo renders one of your Angular components on a page, next to its source code. Readers see the component working and the code that builds it, and the code can't drift, because NgDoc reads it from the component's own files.

👀 See it

The toolbar switches between the Preview and the source files of the component. On the preview, the width buttons show the demo at full width, 480 pixels or 280 pixels, and the copy button copies the open source file, or on the preview, the file that would open first.

The fullscreen button shows the demo on its own, centred on its canvas at the size of the screen. Press Esc, or the button in the corner of the screen, to leave fullscreen. Browsers that don't support fullscreen don't show the button.

🧰 Use it

1. Write a standalone component for the demo, usually next to the page.

2. Add it to the demos of the page:

   ng-doc.page.tsTypeScript

   import { NgDocPage } from '@ng-doc/core';
   
   import { ButtonDemoComponent } from './button-demo/button-demo.component';
   
   const MyPage: NgDocPage = {
     title: 'Buttons',
     mdFile: './index.md',
     demos: { ButtonDemoComponent },
   };
   
   export default MyPage;

3. Render it in the Markdown with the demo action and the key you used in demos:

   index.mdTwig

   {{ NgDocActions.demo("ButtonDemoComponent") }}

The source tabs are the component's files: its TypeScript file, and its template and styles when they are separate files. Each tab is named after the language of its file, such as TypeScript, HTML or SCSS. To show only part of a file, or to name the tabs yourself, use snippets (Snippets).

The demo component can import anything your application can. If it is declared in an NgModule instead of being standalone, add the module to the imports of the page.

📋 Options

Pass options as the second argument of demo. They follow NgDocDemoActionOptions:

{{ NgDocActions.demo("ButtonDemoComponent", { expanded: true, tabs: ["HTML"] }) }}

With expanded, the demo opens on the snippet marked opened, then on defaultTab, then on the first file.

This demo shows only the template, and opens on it:

<button [color]="color()" (click)="clickEvent()" ng-doc-button-flat>Just a button</button>

This one has no container:

{{ NgDocActions.demo("ButtonDemoComponent", { container: false }) }}

Inputs

Give the demo component inputs, and set them where you render the demo with the inputs option. One component can then show several variants.

import { ChangeDetectionStrategy, Component, input } from '@angular/core';
import { NgDocButtonComponent, NgDocColor } from '@ng-doc/ui-kit';

@Component({
  selector: 'ng-doc-button-inline-demo',
  imports: [NgDocButtonComponent],
  template: `<button ng-doc-button [color]="color()">Button</button>`,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ButtonInlineDemoComponent {
  readonly color = input<NgDocColor>('primary');
}

{{ NgDocActions.demo("ButtonInlineDemoComponent", { inputs: { color: "info" } }) }}

NgDoc sets the inputs once, when it renders the demo.

Open in a new tab

To let readers open a demo on its own page, add a child route for it to the route of the page in ng-doc.page.ts:

import { NgDocPage } from '@ng-doc/core';
import { ButtonDemoComponent } from './button-demo.component';

const MyAwesomePage: NgDocPage = {
  title: 'MyAwesomePage',
  mdFile: './index.md',
  demos: { ButtonDemoComponent },
  route: {
    children: [
      {
        path: 'button',
        component: ButtonDemoComponent,
      },
    ],
  },
};

export default MyAwesomePage;

Then pass the path of the route as the fullscreenRoute option. A link that opens the route in a new tab replaces the demo. The route is a standalone page: the demo alone on the dotted canvas, with a small link back to the page in the corner, and without the navbar, the sidebar, the table of contents or the page content. Your app.html needs no changes for it, and the server renders and prerenders the route the same way.

{{ NgDocActions.demo("ButtonDemoComponent", { fullscreenRoute: "button" }) }}

Disable fullscreen routes

To render the child routes of a page yourself, instead of as standalone pages, set disableFullscreenRoutes in ng-doc.page.ts. You will then need a <router-outlet /> in your page (for example in the demo).

By default disableFullscreenRoutes is false.

import { NgDocPage } from '@ng-doc/core';
import { MasterDetailComponent } from './master-detail.component';
import { MasterComponent } from './master.component';
import { DetailComponent } from './detail.component';

const MyAwesomePage: NgDocPage = {
  title: 'MyAwesomePage',
  mdFile: './index.md',
  demos: { MasterDetailComponent },
  disableFullscreenRoutes: true,
  route: {
    children: [
      {
        path: '',
        component: MasterComponent,
      },
      {
        path: ':id',
        component: DetailComponent,
      },
    ],
  },
};

export default MyAwesomePage;

Customization

Style every demo with CSS variables in your global styles:

:root {
  --ng-doc-demo-displayer-border: 1px solid var(--ng-doc-border-color);
  --ng-doc-demo-displayer-border-radius: 12px;
  --ng-doc-demo-displayer-background: var(--ng-doc-base-1);
  --ng-doc-demo-toolbar-background: var(--ng-doc-base-2);
}

To style one demo, give it a class with the class option and set the variables on that class:

{{ NgDocActions.demo("ButtonDemoComponent", { class: "wide-demo" }) }}

.wide-demo {
  --ng-doc-demo-displayer-background: var(--ng-doc-base-2);
}

🚧 Gotchas

Warning

The --ng-doc-demo-displayer-* variables style playgrounds and demo panes too.

Note

The width buttons resize the demo's frame, not the window, so media queries in the demo don't respond to them.

Note

Fullscreen shows only the demo's own element. Something the demo opens outside it, such as an overlay attached to body, isn't visible until the demo leaves fullscreen. Use fullscreenRoute for such demos.

Next: Demo pane