Porsche Design System

Vanilla Js

Table of Contents

Quick start
Integration

Quick start#

To build a Vanilla JS application using the Porsche Design System, follow these steps. This guide is based on the following dependencies:

vite@8

tailwindcss@4

@porsche-design-system/components-js@4

# Create a new application by executing:
npm create vite@latest my-app -- --template vanilla-ts

You're all set! Start building your own application now.

Integration#

Step 1

Install the Porsche Design System within your project directory.

npm install @porsche-design-system/components-js

Step 2

Create a vite.config.ts file in your project directory and integrate the Porsche Design System Loader into the <body> section of your HTML.

// vite.config.ts

import { defineConfig } from 'vite';
import { getLoaderScript } from '@porsche-design-system/components-js/partials';

const transformIndexHtmlPlugin = () => {
  return {
    name: 'html-transform',
    transformIndexHtml(html: string) {
      const bodyPartials = [getLoaderScript()].join('');

      return html.replace(/<\/body>/, `${bodyPartials}$&`);
    },
  };
};

export default defineConfig({
  plugins: [transformIndexHtmlPlugin()],
});

Step 3

Add the PDS Stylesheet to your main CSS file — this single import covers all required and recommended global styles (for websites primarily targeting users in China, use the /cn import instead, see China CDN).

/* src/style.css */
+ @import '@porsche-design-system/components-js';

Disable the lightningcss polyfill for the light-dark() CSS function since it's broken. Learn more

// vite.config.ts

+ import { Features } from 'lightningcss';

export default defineConfig({
+ css: {
+   transformer: 'lightningcss',
+   // disables light-dark() polyfill of lightningcss which is broken https://github.com/porsche-design-system/porsche-design-system/issues/4257
+   lightningcss: {
+     exclude: Features.LightDark,
+   },
+ },
});

To prevent FOUC, hide elements until they are either registered (:defined) or fully rendered by Stencil (.hydrated). If you run into issues with the :defined pseudo-class, scope the style to specific tags instead (e.g., :is(p-button, p-accordion, …):not(:defined)). See Initialization for more details.

/* src/style.css */
@import '@porsche-design-system/components-js';

+ :not(:defined) {
+   visibility: hidden;
+ }

Step 4 (recommended)

To improve your web application's loading performance, integrate Partials from the Porsche Design System into the <head> section of your HTML to preload fonts, icons, and component chunks.

// vite.config.ts

import { defineConfig } from 'vite';
import {
   getLoaderScript,
+  getComponentChunkLinks,
+  getFontLinks,
+  getIconLinks,
+  getMetaTagsAndIconLinks,
} from '@porsche-design-system/components-js/partials';

const transformIndexHtmlPlugin = () => {
  return {
    name: 'html-transform',
    transformIndexHtml(html: string) {
+     const headPartials = [
+       // preloads fonts
+       getFontLinks(),
+       // preloads components
+       getComponentChunkLinks(),
+       // preloads icons
+       getIconLinks(),
+       // injects favicon, apple touch icons, android touch icons, etc.
+       getMetaTagsAndIconLinks({ appTitle: 'Porsche' }),
+     ].join('');

      const bodyPartials = [getLoaderScript()].join('');

+     return html.replace(/<\/head>/, `${headPartials}$&`).replace(/<\/body>/, `${bodyPartials}$&`);
    },
  };
};

export default defineConfig({
  plugins: [transformIndexHtmlPlugin()],
});

Step 5 (recommended)

Setting up Tailwind CSS with the Porsche Design System Tailwind CSS Theme allows you to use a utility-first CSS framework that guarantees seamless styling consistency with Porsche's design principles.

Install Tailwind CSS within your project directory.

npm install tailwindcss @tailwindcss/vite

Configure the Vite Tailwind CSS plugin.

// vite.config.ts

+ import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
+ plugins: [transformIndexHtmlPlugin(), tailwindcss()],
});

Import Tailwind CSS and the Porsche Design System Tailwind CSS Theme.

/* src/style.css */
@import '@porsche-design-system/components-js';

+ @import 'tailwindcss';
+ @import '@porsche-design-system/components-js/tailwindcss';

Step 6

Add a Porsche Design System component (e.g., <p-wordmark></p-wordmark>) with some Tailwind CSS styles. Then, run npm run dev and verify that the component and styles display correctly.

// src/main.ts

import './style.css';

document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
  <div class="grid justify-items-center gap-fluid-md m-static-lg p-fluid-lg bg-surface rounded-lg">
    <p-wordmark></p-wordmark>
    <h1 class="prose-heading-4xl">Porsche Design System</h1>
  </div>
  <div class="…">…</div>
`;