Kanban Bases View

Kanban Bases View Plugin for Obsidian

A kanban-style drag-and-drop custom view for Obsidian Bases that allows you to organize your notes into columns based on any property.

Demo

Features

• Dynamic Column Generation: Select any property from your base to generate kanban columns automatically
• Drag and Drop: Move cards between columns with smooth animations
• Quick Add Buttons: Create new cards directly from a column's + button with the column value, and swimlane value when used, filled in automatically
• Column Reordering: Drag columns by their handle (⋮⋮) to reorder them to your preference
• Swimlanes: Optionally group the board into horizontal lanes using a second property
• Column Color Themes: Assign colors to columns using the color picker button for visual categorization
• Column Order Persistence: Your column order is saved per property and persists across sessions
• Property Selection: Choose which property determines your columns (e.g., "Status", "Priority", "Category")
• Uncategorized Entries: Notes without a value for the selected property are automatically grouped in an "Uncategorized" column
• Property Display: Selected properties are shown on each card for at-a-glance context
• Custom Card Titles: Display a frontmatter property as the card title instead of the file name — useful when files share a common name (e.g., README.md) across folders
• Cover Images: Show a cover image on each card by picking a frontmatter property — mirrors Obsidian's native Cards view Image property with matching fit (cover/contain) and aspect-ratio controls, so one frontmatter field works for both views
• Property Word Wrap: Toggle property text wrapping on cards to handle long property values
• Click to Open: Click any card to open the corresponding note (Cmd/Ctrl+click to open in new tab)
• Visual Feedback: Clear visual indicators during drag operations
• Responsive Design: Works well on different screen sizes

Installation

Manual Installation

1. Download the latest release from the Releases page
2. Extract the plugin folder to your vault's .obsidian/plugins/ directory
3. Reload Obsidian
4. Enable the plugin in Settings → Community plugins

Development Installation

1. Clone this repository:

   git clone https://github.com/xiwcx/obsidian-bases-kanban-custom-view.git
   cd obsidian-bases-kanban-custom-view
   

2. Install dependencies:

   npm install
   

3. Build the plugin:

   npm run build
   

4. Link or copy the plugin folder to your vault's .obsidian/plugins/ directory

Usage

1. Create or open a Base in Obsidian
2. Add a view and select "Kanban" as the view type
3. Select the property you want to use for columns (e.g., "Status") in the "Group by" option
4. Your notes will be automatically organized into columns based on the selected property's values
5. Drag cards between columns to update the property value
6. Optionally, set "Add card to column folder" to a folder path — this enables a + button in each column header for quickly creating cards with that column's value pre-filled
7. Click any card to open the corresponding note (Cmd/Ctrl+click to open in new tab)
8. Drag columns by their handle (⋮⋮) to reorder them - your preferred order will be saved
9. Optionally, select a property in "Swimlane by" to split the board into horizontal lanes
10. Optionally, select a property in "Card title property" to display that property's value as each card's title instead of the file name

Example

If your base has a "Status" property with values "To Do", "Doing", and "Done":

• Select "Status" in the "Group by" dropdown
• Three columns will appear: "To Do", "Doing", and "Done" (plus an "Uncategorized" column for notes without a status)
• Drag cards between columns to change their status
• If "Add card to column folder" is configured, click the + button to create a new note with that status in that folder
• Click any card to open the note (Cmd/Ctrl+click to open in new tab)
• Drag columns by their handle to reorder them - your order preference will be remembered

If your base also has a "Priority" property with values "High", "Medium", and "Low":

• Select "Status" in the "Group by" dropdown
• Select "Priority" in the "Swimlane by" dropdown
• The board will render one horizontal lane for each priority, and each lane will contain the same status columns
• Drag cards sideways to change their status, or drag them to another lane to change their priority
• Click a + button inside a lane to create a new note with both its status and priority filled in
• Drag lane headers to reorder lanes, use the lane toggle to collapse or expand a lane, and drag any column header to reorder that column across all lanes
• Notes without a value for the swimlane property appear in an "Uncategorized" lane
• Leave "Swimlane by" unset to use the original single-axis kanban layout

If your project folders each contain a README.md with a title property:

• Select title in the "Card title property" dropdown
• Cards will display the title property value instead of "README"
• If a note is missing the property, the file name is used as a fallback

If your notes have a frontmatter property pointing at a cover image (e.g., cover: "[[book-cover.jpg]]" or cover: "https://example.com/poster.jpg"):

• Select that property in the "Image property" dropdown
• Each card gets a cover image above the title
• Use "Image fit" to choose between Cover (crop to fill) and Contain (letterbox)
• Drag the "Image aspect ratio" slider to size the cover — wide banner on the left, tall portrait on the right
• The same property value also works in Obsidian's built-in Cards view, so the two views stay in sync

Development

Prerequisites

• Node.js (v24)
• npm

Building

npm run build

Development Mode

npm run dev

This will watch for changes and rebuild automatically.

Testing

npm test

Type Checking

npm run typecheck

Linting and Formatting

This project uses ESLint for linting and Biome for formatting. They are intentionally kept separate.

Lint (reports rule violations):

npm run lint

Lint with auto-fix:

npm run lint:fix

Format (rewrites files):

npm run format

Check formatting (exits non-zero if unformatted; used by CI and the pre-commit hook):

npm run format:check

Technical notes

• The plugin uses the .obk- CSS class prefix (Obsidian Bases Kanban) for all view UI classes to avoid collisions with other plugins and themes.

Releasing

Changesets

Every ordinary PR must add a changeset:

npm run changeset

Select patch for fixes, minor for features, or major for breaking changes. A major bump from 0.x produces 1.0.0. Describe the user-facing change; the summary becomes release notes. For docs, tests, or tooling changes that do not need a release, use npm run changeset -- --empty instead. Missing changesets block CI; do not manually bump version files in ordinary PRs.

Creating a release PR

Release PRs are opened by maintainers, not a bot. No GitHub App, PAT, or npm publishing is needed.

1. Update main, create a release branch, and ensure tracked changes are committed:

   git switch main
   git pull --ff-only
   git switch -c release/next
   npm ci
   npm run version
   

2. Review the generated CHANGELOG.md and version updates in package.json, package-lock.json, manifest.json, and versions.json. The command consumes all pending changesets and preserves historical minimum-app-version mappings. Empty changesets alone do not trigger a release. Historical releases are not backfilled into the changelog.
3. Run npm run format, npm run lint, npm test, and npm run build. Commit the generated changes, push the branch, and open a PR against main.
4. Wait for the required test and build checks, then merge when ready to publish. Release PRs are validated against the base branch's Changesets plan and need no additional changeset. Keep them limited to generated release files; change plugin code or minAppVersion in a normal PR first. If more changesets land on main, update the release branch and regenerate before merging.
5. CI on main builds and attests the plugin, creates the exact version tag (no v), and publishes main.js, manifest.json, and styles.css as individual GitHub release assets. Notes come from the new changelog entry. The npm package is private to prevent accidental npm publication; the GitHub repository and plugin releases remain public.

Published releases are left untouched. Failed uploads leave a draft that CI can resume: rerun the failed job for the same commit. You can also use Actions → CI → Run workflow on main when it still points to the intended release commit. Never reuse an existing tag for a different commit.

Repository protection

main requires a pull request and passing test and build checks against an up-to-date branch. Force pushes and branch deletion are blocked. Another person's approval is not required, so a solo maintainer can merge their own release PR. The changeset requirement runs inside test. The repository's Actions PR-creation setting can remain disabled because maintainers open PRs themselves.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the required changeset and verification steps.

License

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

Acknowledgments

• Built with SortableJS for drag-and-drop functionality
• Inspired by the need for better task management in Obsidian Bases