Buttons Panel

approved

by Kevin

Create customizable button panels for quick access to files, commands, links, and scripts. - This plugin has not been manually reviewed by Obsidian staff.

4 stars1,757 downloadsUpdated 6d agoMIT

Buttons Panel

Obsidian Downloads GitHub Downloads

[中文 | English | Русский]

Buttons Panel is a modern Obsidian plugin that lets you create a customizable button panel for quick access to files, commands, links, and scripts.

✨ 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:

ModeIconBehavior
🔒 LockedlockView only — all interactions disabled (no drag, no context menu)
↕️ Sortarrow-up-downLong-press drag to reorder buttons and categories
✏️ EditpencilRight-click / long-press menu to add, edit, copy, or delete
  • 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.

FeatureDescription
Open/CloseClick a tile to expand; click outside, press ESC, or click blank space (configurable) to close
📌 PinClick 📌 to lock — folder stays open until unpinned or you switch folders
Edit nameClick folder name to rename (configurable in settings)
Reorder foldersLong-press drag in sort mode
Cross-folder dragDrag button out → auto-close → hover 0.6s on another tile → auto-expand → continue sorting
Auto-scrollDrag near edges inside expanded folder to scroll

📦 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):

TargetList viewTabbed viewFolder view
ButtonsLong-press a button, then drag to reorder within a category; drag over another category's tab/zone to move across categoriesSame; active tab's grid supports drag reorderDrag within expanded folder or between folders; hover 0.6s over a tile to auto-expand
CategoriesLong-press the category block (title or non-button area), then drag vertically to reorderLong-press a tab, hold ~0.4s over another tab to confirm drop target, then release to reorderLong-press a tile to reorder in grid
  • 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:

🙏 Acknowledgements

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

For plugin developers

Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.