<p>[<a href="https://github.com/TracingOrigins/obsidian-buttons-panel-plugin/blob/master/README.zh.md">中文</a> | English | <a href="https://github.com/TracingOrigins/obsidian-buttons-panel-plugin/blob/master/README.ru.md">Русский</a>]</p>
<p><a href="https://community.obsidian.md/plugins/buttons-panel" target="_blank">Buttons Panel</a> is a modern Obsidian plugin that lets you create a customizable button panel for quick access to files, commands, links, and scripts.</p>

✨ Features

• 🎯 Quick Access: Instantly open files, execute commands, visit links, or run scripts with a single click.

• 🎨 Icon Options: Search and preview from the Lucide icon library, plus support for custom SVG icons.

• 🏷️ Three View Modes: Switch between list, tabbed, and folder views.

• 📁 Folder View: Android-style folder grid with drag-and-drop, auto-expand on hover, pin to keep open, click-to-close, and editable folder names.

• 📁 Category Management: Organize buttons by category; reorder categories and buttons via long-press drag-and-drop.

• ⚙️ Flexible Configuration: Fully customizable panel layout, button styles, and animation effects.

• 📱 Cross-Platform: Works on all platforms supported by Obsidian (Windows, macOS, Linux, iOS, Android).

• 🌙 Theme Adaptation: Seamlessly adapts to Obsidian’s light and dark themes.

• 🔄 Live Updates: All changes take effect immediately—no restart required.

• 🛡️ Form Validation: Required fields (button name, file path, command ID, URL, folder, script name) are highlighted in red if empty for intuitive feedback.

• 🖱️ Interaction Mode: Three modes — Locked (view only), Sort (drag to reorder), Edit (create/edit/delete via context menu) — switchable from the top navigation bar.

• 🧭 Top Navigation Bar: Dropdown menus to quickly switch panel view, button style, and interaction mode; plus search and settings access.

• 🔍 Search Feature: The navigation bar includes a search function that filters categories and buttons in real-time for quick access.

• 🔗 Action Sequences: Configure multiple actions for a single button and execute them in order with one click.

🚀 Installation

🏪 Install from Community Plugins (Recommended)

1. Open Obsidian and go to Settings → Community Plugins.
2. Click Browse and search for "Buttons Panel".
3. Click Install, then Enable.

📦 Manual Installation

1. Download the latest main.js, manifest.json, and styles.css from Releases.
2. Create a buttons-panel folder under your Obsidian plugins directory (e.g. YourVault/.obsidian/plugins/buttons-panel/) and place the three files inside.
3. Enable the plugin in Obsidian under Settings → Community Plugins.

🔧 Install via BRAT (Recommended for Beta Users)

1. Install the BRAT plugin.
2. In BRAT settings, click "Add Beta plugin".
3. Enter TracingOrigins/obsidian-buttons-panel-plugin.
4. Enable the plugin.

📖 Usage

🎯 Button Panel

Use the command palette (Ctrl+P) and run "Open buttons panel", or click the ribbon icon to quickly open the panel.

• View Mode: Switch between list, tabbed, or folder view from the top navigation bar dropdown.
• Button Style: Switch between icon next to text or icon above text from the top navigation bar dropdown.
• Interaction Mode: Switch between locked, sort, or edit mode from the top navigation bar dropdown.

⚙️ Button Panel Options

Click the settings button in the navigation bar, or go to Settings → Community Plugins → Buttons Panel.

• Show Navigation Bar: Show or hide the top navigation bar.
• Enable Button Animation: Enable or disable hover animation effects for buttons.

List View

• Auto Collapse in List View: When enabled, all categories start collapsed each time you switch to list view.

Tabs View

• Tabs Auto Wrap: When enabled, tabs wrap to the next line instead of horizontal scrolling.

Folder View

• Folder Name Editable: Click the folder name to rename when expanded.
• Show Button Count: Display the number of buttons on the folder tile.
• Close on Blank Click: Click any empty area inside the expanded folder to close it.

Path

• Template Folder Path: Set the folder for template files (e.g., templates/). The create file action uses templates from this path.
• Script Folder Path: Set the folder for script files (e.g., scripts/). The run script action loads scripts from this path.
• One-Click Creation: Click "Create Paths" to automatically create missing folders.

🔗 Buttons & Actions

Action Sequences

• Action Sequences: Configure a button to perform multiple actions in sequence (e.g., create a file, then run a script). Clicking the button executes all actions in order.
  • How to configure: In the button editor, click "Add Action" to add multiple actions and drag to reorder them.
  • Typical use cases: One-click to create and open a template note, batch execute multiple commands, automate daily routines, and more.

Supported Action Types

• Open File: Open any file in your vault.
• Command: Execute any Obsidian command.
• Open Link: Open an external web link.
• Create File: Create a new file at a specified location. The file name supports date variables (e.g., {{DATE:YYYY-MM-DD}}), and content can use a fixed template.
• Run Script: Run a custom JS script from your vault. Scripts must be placed in the folder specified in Path Config.

✅ Form Validation

• When creating or editing a button, clicking "Save" will automatically validate all required fields.
• If any required field is empty, the corresponding input will be highlighted in red.
• The red highlight disappears automatically once the field is filled.

🧭 Top Navigation Bar

• Search: Click the search icon to open a search box. Enter keywords to filter categories and button names in real-time. Clear or close the search box to reset.
• Panel View Switch: Switch between tabbed and list views.
• Button Style Switch: Instantly change button styles.
• Interaction Mode: Dropdown to switch between Locked, Sort, and Edit modes.
• Panel Settings: Quick access to the plugin settings page.
• Tab Bar Scrolling (tabbed view, many tabs): Swipe left/right on mobile; hold Shift and scroll on desktop.

🖱️ Interaction Mode

Click the edit button in the navigation bar to open a dropdown with three modes:

• Switch modes from the navigation bar dropdown or in Panel Config settings.
• Drag-and-drop is only available in Sort mode.
• Editing controls are only available in Edit mode.

📁 Folder View

Switch to folder view from the navigation bar or settings. Categories appear as folder tiles in a responsive grid.

📦 Drag-and-Drop Reordering

When Sort mode is active and search is not active, long-press and drag to reorder (mouse long-press works on desktop too):

• Order is saved automatically when you release.
• Reordering is unavailable in Locked or Edit mode, or while search is active.

📱 Touch Gestures (Mobile)

• Scroll the panel: Swipe up/down on the panel (list view) or left/right on the tab bar (tabbed view) without long-pressing.
• Drag to reorder: Long-press (~0.5s) on a button or category/tab, then drag. While dragging, panel scrolling is locked so the item follows your finger.
• If a quick swipe is detected before the long-press completes, the gesture is treated as scrolling and drag does not start.

Script Feature

• In the button editor, select "Script" as the action type and choose or enter a script file name (.js only).

• Script files must be placed in the folder specified in Path Config (e.g., scripts/).

• Scripts must export an async function via module.exports:

    ```js
    // scripts/hello.js
    module.exports = async function (app, plugin, notice, obsidian) {
    const { FuzzySuggestModal } = obsidian;
    notice('Hello from script!');
  

  }; ```

Or define the function first:

```js
// scripts/hello.js
module.exports = hello;

async function hello(app, plugin, notice, obsidian) {
    const { Notice } = obsidian;
    notice('Hello from script!');
}
```

• The following variables are injected into the script function:
  • app — The running obsidian.App instance for interacting with the vault, workspace, etc. Note: this is an instance, not obsidian.App (the class); do not use with new.
  • plugin — The current plugin instance, for accessing plugin settings.
  • notice — A convenience notification function, equivalent to new obsidian.Notice(msg).
  • obsidian — The Obsidian module namespace, for destructuring classes like App, FuzzySuggestModal, Notice, etc.
• Script errors are automatically caught and shown as notifications.
• Security Note: Do not run scripts from untrusted sources.

Example: Configure a button with "Run Command A → Run Command B → Open Link" actions, and they will execute in order with one click.

🛠️ Development

• Clone this repository.
• Make sure your NodeJS is at least v18 (node --version), LTS version recommended.
• Run npm install to install dependencies.
• Run npm run dev to start development mode with live compilation (automatically deploys to test vault).
• Run npm run build to build the production version and deploy to test vault.
• Run npm run lint to check code quality.
• To deploy to a custom vault, create a .env file in the project root and add: VAULT_PATH=/path/to/your/vault.

🎨 Tech Stack

• TypeScript: Type-safe JavaScript with strict mode.
• React: Modern framework for building user interfaces.
• Obsidian API: Official plugin API.
• Lucide Icons: Modern icon library (6000+ icons).
• CSS Grid & Flexbox: Responsive layout.
• ESBuild: Fast build tool with TypeScript and React support.
• @dnd-kit: Drag-and-drop for button and category reordering.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🌟 Support & Help

If you find this plugin helpful, please consider:

• ⭐ Starring the repository.
• 🐛 Using the bug report template to submit bug reports.
• 💡 Using the feature request template to submit feature suggestions.
• ❓ Asking questions or sharing ideas in our Discussions.
• 📝 Referring to the Contributing Guide to contribute code or documentation.
• 💰 Providing sponsorship to the developer (if available).

🙏 Acknowledgements

This plugin uses icons from the open-source project Lucide, which is licensed under the ISC License.