@ProfPowell/browser-window

A Safari-style browser window web component for demos and tutorials. Features source code viewing, full-screen expand mode, CodePen export, automatic theme detection, and full theming support.

View Documentation | Live Demos | API Reference

Based on @zachleat/browser-window with significant enhancements.

Installation

npm

npm install @profpowell/browser-window

import '@profpowell/browser-window';

CDN

<!-- unpkg -->
<script type="module" src="https://unpkg.com/@profpowell/browser-window"></script>

<!-- jsdelivr -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@profpowell/browser-window"></script>

Direct Download

<script type="module" src="path/to/browser-window.js"></script>

Usage

Basic Usage

<browser-window url="https://example.com" title="My Demo">
  <img src="screenshot.png" alt="Demo screenshot">
</browser-window>

Loading External HTML

<browser-window
  src="demos/my-demo.html"
  url="https://example.com"
  title="CSS Demo">
</browser-window>

Dark Mode

The component automatically respects your system's prefers-color-scheme preference. You can also explicitly set the mode:

<!-- Follows system preference (default) -->
<browser-window src="demo.html"></browser-window>

<!-- Always light -->
<browser-window mode="light" src="demo.html"></browser-window>

<!-- Always dark -->
<browser-window mode="dark" src="demo.html" shadow></browser-window>

Resizable

The component is resizable by default. Drag the bottom-right corner to resize:

<!-- Set initial size with CSS -->
<browser-window src="demo.html" style="height: 400px; width: 600px;">
</browser-window>

Attributes

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | url | string | '' | URL to display in the address bar | | title | string | hostname from url | Title shown in the URL bar | | src | string | '' | Path to HTML file to load in iframe (enables source viewing) | | mode | 'light' | 'dark' | auto | Color scheme. Omit to follow system preference | | shadow | boolean | false | Add drop shadow to the window |

Features

Source Code Viewing

When src is set, a code icon appears in the URL bar. Click to toggle between the rendered content and syntax-highlighted source code.

Maximize Mode

• Double-click the title bar to maximize/restore
• Click the green button to maximize
• Press Escape or click the overlay to restore
• Maximized windows display as a centered modal with backdrop

Share Menu

When src is set, a share button provides:

• Share... - Native Web Share API (on supported devices)
• Open in CodePen - Export demo to CodePen with HTML/CSS/JS separated

Download

Direct download link for the source HTML file.

Automatic Theme Detection

The component automatically follows your operating system's light/dark mode preference using prefers-color-scheme. Set the mode attribute to override this behavior.

Resizable Container

Drag the bottom-right corner to resize the component. The content area (iframe or source view) automatically adjusts to fill the available space. Resizing is disabled when maximized.

Mobile-Friendly

• Touch-friendly control buttons with proper hit targets (44px minimum)
• Responsive layout that adapts to narrow screens
• URL bar text truncates gracefully on small screens

CSS Custom Properties

All visual aspects can be customized via CSS custom properties:

browser-window {
  --browser-window-bg: #ffffff;
  --browser-window-header-bg: #f6f8fa;
  --browser-window-border-color: #d1d5da;
  --browser-window-border-radius: 8px;
  --browser-window-text-color: #24292e;
  --browser-window-text-muted: #586069;
  --browser-window-url-bg: #ffffff;
  --browser-window-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  --browser-window-close-color: #ff5f57;
  --browser-window-minimize-color: #febc2e;
  --browser-window-maximize-color: #28c840;
  --browser-window-accent-color: #2563eb;
  --browser-window-hover-bg: #f3f4f6;
  --browser-window-content-bg: #ffffff;
  --browser-window-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  --browser-window-mono-font: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
}

Custom Theme Example

/* Purple theme */
browser-window.purple-theme {
  --browser-window-accent-color: #8b5cf6;
  --browser-window-header-bg: #faf5ff;
  --browser-window-border-color: #c4b5fd;
}

Accessibility

• Full keyboard navigation with visible focus indicators
• ARIA labels on all interactive elements
• role="dialog" and aria-modal when maximized
• Respects prefers-reduced-motion for animations
• Escape key closes maximized view and menus
• Touch targets meet WCAG 2.1 minimum size requirements

Browser Support

Works in all modern browsers that support Web Components:

• Chrome/Edge 67+
• Firefox 63+
• Safari 10.1+

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run linter
npm run lint

# Run tests
npm test

# Build for production
npm run build

# Generate custom elements manifest
npm run analyze

Scripts

| Script | Description | |--------|-------------| | npm run dev | Start local dev server on port 3456 | | npm run build | Build for production (JS + types) | | npm run lint | Run ESLint | | npm run lint:fix | Run ESLint with auto-fix | | npm run format | Format code with Prettier | | npm run test | Run test suite | | npm run test:watch | Run tests in watch mode | | npm run analyze | Generate custom-elements.json manifest |

Related Projects

• <code-block> - Syntax-highlighted code block web component with copy button
• @zachleat/browser-window - The original component this project is based on

License

MIT