Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/agmmnn/tauri-controls
🚥 Native-looking window controls for Tauri 2. React, Solid, Vue, Svelte+Tailwind.
https://github.com/agmmnn/tauri-controls
cross-platform desktop desktop-app macos tauri tauri-app tauri-plugin windows
Last synced: 2 days ago
JSON representation
🚥 Native-looking window controls for Tauri 2. React, Solid, Vue, Svelte+Tailwind.
- Host: GitHub
- URL: https://github.com/agmmnn/tauri-controls
- Owner: agmmnn
- License: mit
- Created: 2023-07-24T13:19:35.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-08-11T02:54:24.000Z (6 months ago)
- Last Synced: 2024-10-29T17:33:12.011Z (3 months ago)
- Topics: cross-platform, desktop, desktop-app, macos, tauri, tauri-app, tauri-plugin, windows
- Language: TypeScript
- Homepage: https://npmjs.com/package/tauri-controls
- Size: 3.44 MB
- Stars: 665
- Watchers: 8
- Forks: 27
- Open Issues: 15
-
Metadata Files:
- Readme: .github/README.md
Awesome Lists containing this project
README
[](https://bundlephobia.com/)
[](https://bundlephobia.com/)
[](https://npmjs.com/package/tauri-controls)
[](https://www.npmjs.com/package/tauri-controls) [](https://www.npmjs.com/package/@tauri-controls/svelte) [](https://www.npmjs.com/package/@tauri-controls/solid) [](https://www.npmjs.com/package/@tauri-controls/vue)
**Tauri Controls** is a library that provides native-looking **window controls** for [Tauri 2](https://beta.tauri.app) applications. You can enhance the user experience of your Tauri 2 applications with window controls that mimic the identical native controls on the current system.
`tauri-controls` uses Tauri's [js/ts APIs](https://next--tauri.netlify.app/next/api/js) to handle window events and just provides native-looking (designed according to official system design prototypes) html elements, not native, _it does not rely on the system's native APIs_.
The following designs are taken as reference:
- [Windows UI 3](https://www.figma.com/community/file/1159947337437047524) @microsoft
- [Apple Design Resources - macOS](https://www.figma.com/community/file/1251588934545918753) @apple
## How to use
### Install Dependencies
```bash
# React:
bun add tauri-controls
# Svelte:
bun add @tauri-controls/svelte
# Solid.js:
bun add @tauri-controls/solid
# Vue.js:
bun add @tauri-controls/vue
```
```bash
# Install peer dependencies:
bun add @tauri-apps/plugin-os @tauri-apps/api
bun add -D clsx tailwind-merge
```
> For **Svelte** projects, include the following line in the `content` section of your `tailwind.config.js`:
>
> ```js
> "./node_modules/@tauri-controls/svelte/**/*.{js,svelte,ts}"
> ```
Then, make sure to include the following tauri plugins in your `src-tauri` directory:
```bash
cargo add tauri-plugin-window tauri-plugin-os
```
Don't forget to register plugins in your main function.
```rust
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_os::init())
.plugin(tauri_plugin_window::init())
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
> _If you get the message "Not allowed by scope" in the terminal after a production build, try [this](https://github.com/agmmnn/tauri-controls/issues/1#issuecomment-1653557673)._
### Add to Your Code
And simply add the `WindowTitlebar` or `WindowControls` component to your code, depending on your needs:
#### WindowTitlebar
The `WindowTitlebar` component handles the window titlebar and dynamically adjusts the **window control buttons** and **titlebar content** order based on the current operating system.
```tsx
import { WindowTitlebar } from "tauri-controls"
function MyTitlebar() {
return (
{/* Place your titlebar content here */}
)
}
```
When no platform is specified, the current system will be detected and the matching element will be returned. This feature is a great solution for cross-platform releases.
#### WindowControls
Use the `WindowControls` component only for window controls.
```tsx
import { WindowControls } from "tauri-controls"
function MyTitlebar() {
return
}
```
### More examples:
- [in React](https://github.com/agmmnn/tauri-controls/blob/master/apps/tauri-controls/src/App.tsx)
- [in Svelte](https://github.com/agmmnn/tauri-controls/blob/master/apps/tauri-controls-svelte/src/routes/%2Bpage.svelte)
- [in Solid.js](https://github.com/agmmnn/tauri-controls/blob/master/apps/tauri-controls-solid/src/App.tsx)
- [in Vue.js](https://github.com/agmmnn/tauri-controls/blob/master/apps/tauri-controls-vue/src/App.vue)
## Options
### `WindowTitlebar`:
- `controlsOrder?: "right" | "left" | "platform" | "system"`: Specifies the order of window controls. **platform**: to get OS-based positioning specified in _windowControlsProps_.
**system**: to automatically detect the platform and position the controls accordingly (default).
- `windowControlsProps?: WindowControlsProps`: Additional props to pass to the `WindowControls` component.
### `WindowControls`:
- `platform?: "windows" | "macos" | "gnome"`: Specifies which platform's window controls to display. If the _platform_ property is not specified, the library will automatically detect the operating system the app is running on and display the appropriate element.
- `justify?: boolean`: If set to `true`, `WindowControls` will justify/snap in the flexbox where it is located.
- `hide?: boolean`: If set to `true`, the window controls will be hidden.
- `hideMethod?: "display" | "visibility"`: Determines how the window controls will be hidden.
You can also provide additional props to elements, such as `data-tauri-drag-region`, for further enhancements.
## Figma
Check out the design implementation on Figma for a visual reference. [Desktop Native Window Controls - Figma](https://www.figma.com/file/ms2vbZx5lEGxHqHR8fAfQm/Desktop-Native-Window-Controls?type=design&node-id=4%3A6020&mode=design&t=PIbVTsr8zWmIFsNr-1).
These sources were utilized:
- [Windows UI 3](https://www.figma.com/community/file/1159947337437047524) @microsoft
- [Apple Design Resources - macOS](https://www.figma.com/community/file/1251588934545918753) @apple
- [macOS Monterey UI Kit for Figma](https://www.figma.com/community/file/1034539431656086181/macOS-Monterey-UI-Kit-for-Figma) @joey
- [Spotify Desktop App Clone](https://www.figma.com/community/file/1028665514709480268/Spotify-Desktop-App-Clone) @uidesignguide
## Development and Contribution
```bash
bun dev
bun tauri:dev
```
Project Structure:
```bash
.
├── /apps
│ ├── /tauri-controls # Main application (React)
│ ├── /tauri-controls-solid # Solid.js implementation
│ └── /tauri-controls-svelte # Svelte implementation
├── /packages # Shared packages
├── package.json # Project configuration
├── pnpm-workspace.yaml # Workspace configuration
└── turbo.json # TurboRepo configuration
```
If you're interested in contributing, check out our [TODO list](https://github.com/agmmnn/tauri-controls/blob/master/TODOs.md) for tasks you can help with. Your contributions are appreciated!
## Contributors
This project is made possible by the contributions of various individuals. Thank you to all the contributors who have helped make this project better.
- **[tauri-controls](https://www.npmjs.com/package/tauri-controls), [@tauri-controls/svelte](https://www.npmjs.com/package/@tauri-controls/svelte)**: [@agmmnn](https://github.com/agmmnn)
- **[@tauri-controls/solid](https://www.npmjs.com/package/@tauri-controls/solid)**: [@ronanru](https://github.com/ronanru)
- **[@tauri-controls/vue](https://www.npmjs.com/package/@tauri-controls/vue)**: [@allenli178](https://github.com/allenli178)
## Further Reading
- [Feature request: Add setting for titlebar style with native window controls support - tauri-apps/tauri#2663](https://github.com/tauri-apps/tauri/issues/2663)
- [Window Controls Overlay for Installed Desktop Web Apps - WICG](https://github.com/WICG/window-controls-overlay/blob/main/explainer.md)
- [Window Controls Overlay - Electron](https://www.electronjs.org/docs/latest/tutorial/window-customization#window-controls-overlay-macos-windows)
- [Window Controls Overlay API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API)
## License
MIT