> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# Building a Custom Window

## Electron Capability Mapping

Lynxtron's custom window support is aligned with Electron's custom / frameless window support.

Window shape is controlled by window creation options, and draggable regions are declared through CSS. The difference is that Electron uses `BrowserWindow` and Web pages for these capabilities, while Lynxtron uses `LynxWindow` and Lynx UI.

| Capability                        | Electron                                                                                              | Lynxtron                                                                                               |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Window shape options              | `new BrowserWindow(options)`, such as `frame`, `transparent`, `titleBarStyle`, `trafficLightPosition` | `new LynxWindow(options)` with the same option names                                                   |
| Declare a custom draggable region | CSS: `-webkit-app-region: drag`                                                                       | CSS: `-x-app-region: drag`, or use [`<title-bar-view>`](/next/api/elements/built-in/title-bar-view.md) |

The draggable region CSS is:

```css
/* Electron */
.titlebar {
  -webkit-app-region: drag;
}

/* Lynxtron */
.titlebar {
  -x-app-region: drag;
}
```

## Example: Floating Clock Window


**This is an example below: floating-clock**

**Bundle:** `dist/desktop/main.lynx.bundle`

```tsx
import { useState, useEffect, useCallback } from "@lynx-js/react";
import { CustomTitleBar } from "./components/CustomTitleBar";
import "@lynxtron-examples/config/tokens.css";
import "./App.css";

function formatTime(date: Date): string {
  const hours = date.getHours().toString().padStart(2, "0");
  const minutes = date.getMinutes().toString().padStart(2, "0");
  const seconds = date.getSeconds().toString().padStart(2, "0");
  return `${hours}:${minutes}:${seconds}`;
}

// Uppercase must be literal in the string — text-transform is dropped at compile.
const DAYS = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
const MONTHS = [
  "JAN", "FEB", "MAR", "APR", "MAY", "JUN",
  "JUL", "AUG", "SEP", "OCT", "NOV", "DEC",
];

function formatDate(date: Date): string {
  const day = date.getDate().toString().padStart(2, "0");
  return `${DAYS[date.getDay()]} · ${MONTHS[date.getMonth()]} ${day}`;
}


export function App() {
  const [time, setTime] = useState(formatTime(new Date()));
  const [isHovered, setIsHovered] = useState(false);

  useEffect(() => {
    const timer = setInterval(() => {
      setTime(formatTime(new Date()));
    }, 1000);
    return () => clearInterval(timer);
  }, []);

  const handleClose = useCallback(() => {
    // @ts-ignore
    NativeModules.bridge.call("close", {}, () => {});
  }, []);

  const handleMouseEnter = useCallback(() => {
    setIsHovered(true);
  }, []);

  const handleMouseLeave = useCallback(() => {
    setIsHovered(false);
  }, []);

  return (
    <view
      className={`app-container`}
      bindmouseenter={handleMouseEnter}
      bindmouseleave={handleMouseLeave}
    >
      <CustomTitleBar
        onClose={handleClose}
        visible={isHovered}
      />
      <view className="clock-container">
        <text className="clock-text">{time}</text>
        <text className="clock-date">{formatDate(new Date())}</text>
      </view>
    </view>
  );
}

```



This demo uses a floating clock to show a custom window: the window itself is frameless and transparent, the clock UI is drawn by the app, and a custom draggable title bar appears when the mouse hovers over the window.

### Define the Window Shape

The window shape is controlled by `LynxWindow` creation options. Common options include:

- `frame: false`: remove the system default border and title bar.
- `transparent: true`: create a transparent window.
- `titleBarStyle`: hide or adjust the system title bar.
- `trafficLightPosition`: adjust the macOS traffic light button position in frameless windows.

For example, create a frameless transparent window:

```typescript
import { app, LynxWindow } from '@lynx-js/lynxtron';
import path from 'node:path';

app.whenReady().then(() => {
  const win = new LynxWindow({
    width: 960,
    height: 640,
    frame: false,
    transparent: true,
  });
  win.loadFile(path.join(__dirname, 'main.lynx.bundle'));
  win.show();
});
```

### Define UI Draggable Regions

After the system title bar is removed, a frameless window no longer has a default system draggable region. You need to explicitly declare which regions in Lynx UI can drag the window.

You can use [`<title-bar-view>`](/next/api/elements/built-in/title-bar-view.md), or use the `-x-app-region: drag` CSS property. The following example declares a custom title bar region with CSS:

```tsx {3}
export function CustomTitleBar() {
  return (
    <view className="title-bar">
      <view className="title-bar-button" bindtap={handleClose}>
        <text className="title-bar-button-text">×</text>
      </view>
    </view>
  );
}
```

```css
.title-bar {
  display: flex;
  ...
  -x-app-region: drag;
}
```

Buttons such as close, minimize, and maximize in a custom title bar can call main-process window APIs through [Node.js and Lynx communication](/next/lynxtron/learn/Communication-Between-Node-And-Lynx.md).

## Related APIs

- [`LynxWindow`](/next/lynxtron/api/@lynx-js/lynxtron/Class.LynxWindow.md)
- [`LynxWindowConstructorOptions`](/next/lynxtron/api/@lynx-js/lynxtron/Interface.LynxWindowConstructorOptions.md)
- [`<title-bar-view>`](/next/api/elements/built-in/title-bar-view.md)
