@rafaelgm/vue-split-layout

@rafaelgm/vue-split-layout (Vue 3)

Vue 3 component for creating draggable and resizable split layouts. Forked and updated from vue-hxs/vue-split-layout.

Features

• Create horizontal or vertical splits.
• Nest splits for complex layouts.
• Drag panes to rearrange the layout (edit mode).
• Drag splitters to resize panes (resize mode).
• Preserves component state within panes during layout changes.
• Supports standard components or simple div elements as panes.
• Optional Pane component for convenient header/content structure.
• Custom drag handles within panes.
• Built with Vue 3 Composition API.

Installation

npm install @rafaelgm/vue-split-layout
# or
yarn add @rafaelgm/vue-split-layout

Usage

1. Import Components and Styles:

// main.js or your component
import { createApp } from 'vue'
import App from './App.vue'

// Import library styles
import '@rafaelgm/vue-split-layout/style.css';

createApp(App).mount('#app')

2. Use in your Component:

<template>
  <div class="app-container">
    <header>
      <button @click="editMode = !editMode">Toggle Edit ({{ editMode }})</button>
      <button @click="resizeMode = !resizeMode">Toggle Resize ({{ resizeMode }})</button>
      <button @click="saveLayout">Save Layout</button>
    </header>

    <Layout
      class="main-layout"
      :splits="layoutConfig"
      :edit="editMode"
      :resize="resizeMode"
      @layout:update="handleLayoutUpdate"
      @splitResize="handleSplitResize"
    >
      <!-- Child elements MUST have unique keys matching the IDs in layoutConfig -->

      <!-- View/Pane 0 -->
      <Pane title="Pane A (Key 0)" :key="0">
        <div>Content for Pane A</div>
        <input type="text" placeholder="Input A"/>
      </Pane>

      <!-- View/Pane 1 -->
      <div :key="1" style="padding: 10px; background-color: #e0f0ff;">
        <h2>Pane B (Key 1)</h2>
        <p>This is a simple div acting as a pane.</p>
        <textarea placeholder="Text Area B"></textarea>
        <!-- Custom Drag Handle Example -->
        <div style="padding: 5px; background: #ccc; cursor: grab; display: inline-block;" pane-drag-handle>
          DRAG ME HERE
        </div>
      </div>

      <!-- View/Pane 2 -->
      <Pane title="Pane C (Key 2)" :key="2">
        <p>Content for Pane C.</p>
        <input type="text" placeholder="Input C"/>
      </Pane>

    </Layout>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { Layout, Pane } from '@rafaelgm/vue-split-layout';

const editMode = ref(true);
const resizeMode = ref(true);

// Define the layout structure
const layoutConfig = ref({
  dir: 'horizontal', split: '30%', first: 0,
  second: { dir: 'vertical', split: '50%', first: 1, second: 2 }
});

// Handler for layout updates
const handleLayoutUpdate = (newLayoutConfig) => {
  console.log('Layout updated:', newLayoutConfig);
  layoutConfig.value = newLayoutConfig; // Update local state to persist change
  // localStorage.setItem('myLayout', JSON.stringify(newLayoutConfig));
};

// Handler for split resizing
const handleSplitResize = (event, nodeId, newSplitValue) => {
    console.log(`Split ${nodeId} resized to ${newSplitValue}`);
    // If saving layout on resize, might need debounce or save on mouseup
};

const saveLayout = () => {
    console.log('Saving layout:', layoutConfig.value);
     localStorage.setItem('myLayout', JSON.stringify(layoutConfig.value));
};

// Example: Load layout on mount
// onMounted(() => {
//   const savedLayout = localStorage.getItem('myLayout');
//   if (savedLayout) {
//     layoutConfig.value = JSON.parse(savedLayout);
//   }
// });

</script>

<style scoped>
/* ... (styles remain the same) ... */
.app-container { display: flex; flex-direction: column; height: 100vh; width: 100vw; overflow: hidden; }
header { padding: 10px; border-bottom: 1px solid #ccc; flex-shrink: 0; }
.main-layout { flex-grow: 1; position: relative; overflow: hidden; }
:deep(.pane .content div), :deep(.pane .content p), :deep(h2), :deep(p) { margin-bottom: 10px; }
:deep(input[type="text"]), :deep(textarea) { width: 90%; padding: 8px; margin-top: 5px; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box; }
:deep([pane-drag-handle]) { cursor: grab; }
:deep([pane-drag-handle]:active) { cursor: grabbing; }
</style>

3. Layout Configuration (splits prop):

The splits prop defines the layout structure. It's a recursive object where:

• An object with dir ('horizontal' or 'vertical'), first, and second defines a split.
  • split: (Optional) A string percentage (e.g., '30%') defining the size of the first child. Defaults to '50%'.
  • first: The key of the component/element for the first pane (left/top). Can be another split object for nesting.
  • second: The key of the component/element for the second pane (right/bottom). Can be another split object for nesting.
• A primitive value (Number or String) represents the key of a view/pane component/element.

Important: The values used for first and second (when they are not nested split objects) must match the key prop on the direct children passed into the <Layout> component's default slot.

Components

<Layout>

The main container component.

Props:

• splits: (Object, Default: {}) The layout configuration object (see above). Required for defining the layout.
• edit: (Boolean, Default: true) Enables/disables dragging panes to rearrange the layout. When enabled, the entire pane area is draggable unless a pane-drag-handle is specified within the pane.
• resize: (Boolean, Default: true) Enables/disables dragging splitters to resize panes.

Events:

• layout:complete: Emitted after the layout has finished rendering or updating its structure (e.g., on mount, after prop changes, after drag completion).
• splitResize: Emitted during a splitter handle drag and also on release.
  • Payload: (event: MouseEvent, nodeId: Number, newSplitValue: String) - nodeId is an internal ID of the split node, newSplitValue is the new percentage string (e.g., '42.5%'). Note: The layout's internal state is updated automatically. This event is informational.
• layout:update: Emitted after a drag-and-drop operation successfully rearranges the layout.
  • Payload: (newLayoutConfig: Object) - The new layout configuration object, reflecting the structure after the drop. You should use this payload to update your splits prop if you want the change to persist.

Slots:

• default: Place your view components or elements here. Each direct child must have a unique key prop corresponding to the keys used in the splits configuration.

<Pane>

A helper component for structuring content within a layout pane. Provides a distinct header and content area.

Props:

• title: (String, Default: '') Text to display in the pane's header.

Slots:

• default: Content to display below the header within the pane.

Custom Drag Handle

To restrict dragging of a pane (when edit mode is enabled) to a specific handle element inside that pane, add the pane-drag-handle attribute to the desired handle element. If this attribute is not present on any element within a pane, the entire pane content area becomes the drag target.

<Layout :splits="{ first: 0, second: 1 }" :edit="true">
  <div :key="0">Cannot drag me (no handle and not a default draggable area)</div>
  <Pane title="Pane 1" :key="1">
    Content...
    <button pane-drag-handle>Drag Pane 1 ONLY from here</button>
    More content...
  </Pane>
</Layout>

Styling

The library requires its base styles. Import them once in your application:

import '@rafaelgm/vue-split-layout/style.css';

You can override styles using standard CSS techniques by targeting the generated classes (e.g., .layout-container, .split, .splitter, .pane, .header, .content). Use your browser's developer tools to inspect the structure.

TODO / Future Ideas

• Touch Support: Add touch event listeners (touchstart, touchmove, touchend) for mobile/tablet usability.
• Accessibility: Improve WAI-ARIA attributes for draggable/resizable elements.
• Named Views: Potentially allow using string aliases in the splits config instead of numeric keys (would require internal mapping).
• Draggable Views Menu: Allow adding/removing views from a separate menu (feature enhancement).
• Emit layout:update after Resize: Currently, only drag operations emit layout:update. Consider if resizing should also trigger this event (perhaps debounced on mouseup) to allow saving percentage changes easily.

Acknowledgements

This project is a fork and update to Vue 3 of the original vue-split-layout library created by Luis Figueiredo.

• Original Repository: https://github.com/vue-hxs/vue-split-layout
• This Fork (Vue 3): https://github.com/rafaelgm/vue-split-layout

License

MIT License. See the LICENSE file for details.