smfields.BlazorSplit 0.0.3

BlazorSplit

Blazor wrapper around the Split.js library.

• Zero Deps
• Fast: No overhead or attached window event listeners, uses pure CSS for resizing.
• Unopinionated: Only compute view sizes. Everything else is up to you.

View the base library documentation here

Table of Contents

• Installation
• Documentation
• Important Note
• Options
• Flexbox
• CSS
• Browser Support
• License
• Base Library License

Installation

dotnet add package BlazorIntersectionObserver --version 3.1.0

In your Program.cs or Startup.cs use the following to register the required services:

builder.Services.AddBlazorSplit();

Documentation

Basic Use

<Split>
    <SplitSection></Split>
    <SplitSection></Split>
    ...
</Split>

Important Note

Split.js does not set CSS beyond the minimum needed to manage the width or height of the elements. This is by design. It makes Split.js flexible and useful in many different situations. If you create a horizontal split, you are responsible for (likely) floating the elements and the gutter, and setting their heights. See the CSS section below. If your gutters are not showing up, check the applied CSS styles. THIS IS THE #1 QUESTION ABOUT THE LIBRARY.

Options

Sizes

An array of initial sizes of the elements, specified as percentage values. Example: Setting the initial sizes to 25% and 75%.

<Split
    Sizes="new Number[]{ 25, 75 }"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

MinSize. Default: 100

An array of minimum sizes of the elements, specified as pixel values. Example: Setting the minimum sizes to 100px and 300px, respectively.

<Split
    MinSize="new Number[]{ 100, 300 }"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

MaxSize. Default: Infinity

An array of maximum sizes of the elements, specified as pixel values. Example: Setting the maximum sizes of the first element to 500px, and not setting a maximum size on the second element.

<Split
    MaxSize="new Number[]{ 500, Number.PositiveInfinity }"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

If a number is passed instead of an array, all elements are set to the same maximum size:

<Split
    MaxSize="500"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

ExpandToMin. Default: false

When the split is created, if ExpandToMin is true, the minSize for each element overrides the percentage value from the Sizes option. Example: The first section is set to 25% width of the parent container. However, it's MinSize is 300px. Using ExpandToMin: true means that the first element will always load at at least 300px, even if 25% were smaller.

<Split
    Sizes="new Number[]{ 25, 75 }"
    MinSize="new Number[]{ 300, 100 }"
    ExpandToMin="true"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

GutterSize. Default: 10

Gutter size in pixels. Example: Setting the gutter size to 20px.

<Split
    GutterSize="20"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

GutterAlign. Default: 'Center'

Possible options are 'Start', 'End' and 'Center'. Determines how the gutter aligns between the two elements. 'Start' shrinks the first element to fit the gutter, 'End' shrinks the second element to fit the gutter and 'Center' shrinks both elements by the same amount so the gutter sits between.

Example: move gutter to the side of the second element:

<Split
    GutterAlign="GutterAlign.End"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

SnapOffset. Default: 30

Snap to minimum size at this offset in pixels. Example: Set to 0 to disable to snap effect.

<Split
    SnapOffset="0"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

DragInterval. Default: 1

Drag this number of pixels at a time. Defaults to 1 for smooth dragging, but can be set to a pixel value to give more control over the resulting sizes. Works particularly well when the GutterSize is set to the same size.

Example: Drag 20px at a time:

<Split
    SnapOffset="20"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

Direction. Default: 'Horizontal'

Direction to split in. Can be 'Vertical' or 'Horizontal'. Determines which CSS properties are applied (ie. width/height) to each element and gutter. Example: split vertically:

<Split
    Direction="Direction.Vertical"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

Cursor. Default: 'col-resize'

Cursor to show on the gutter (also applied to the body on dragging to prevent flickering). Defaults to 'col-resize'for Direction: 'Horizontal' and 'row-resize' for Direction: 'Vertical':

<Split
    Direction="Direction.Vertical"
    Cursor="row-resize"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

Class

Class name to apply to the container element

<Split
    Class="split-container"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

The example above would result in the following HTML

<div class="split-container">
    <div class="split-section"></div>
    <div class="gutter gutter-horizontal">
    <div class="split-section"></div>
</div>

Style

Styles to apply to the container element

<Split
    Style="display: flex;"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

The example above would result in the following HTML

<div style="display: flex;">
    <div class="split-section"></div>
    <div class="gutter gutter-horizontal">
    <div class="split-section"></div>
</div>

Flex Layout

Flex layout is supported easily by adding a display: flex to the parent element. The width or height CSS values assigned by default by Split.js work well with flex.

<Split
    Class="split"
>
    <SplitSection></SplitSection>
    <SplitSection></SplitSection>
</Split>

And CSS style like this:

.split {
    display: flex;
    flex-direction: row;
}

CSS

In being non-opionionated, the only CSS Split.js sets is the widths or heights of the elements. Everything else is left up to you. You must set the elements and gutter heights when using horizontal mode. The gutters will not be visible if their height is 0px. Here's some basic CSS to style the gutters with, although it's not required. Both grip images are included in this repo:

.gutter {
    background-color: #eee;
    background-repeat: no-repeat;
    background-position: 50%;
}
.gutter.gutter-horizontal {
    background-image: url('grips/vertical.png');
    cursor: col-resize;
}
.gutter.gutter-vertical {
    background-image: url('grips/horizontal.png');
    cursor: row-resize;
}

The grip images are small files and can be included with base64 instead:

.gutter.gutter-vertical {
    background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAFAQMAAABo7865AAAABlBMVEVHcEzMzMzyAv2sAAAAAXRSTlMAQObYZgAAABBJREFUeF5jOAMEEAIEEFwAn3kMwcB6I2AAAAAASUVORK5CYII=');
}
.gutter.gutter-horizontal {
    background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAeCAYAAADkftS9AAAAIklEQVQoU2M4c+bMfxAGAgYYmwGrIIiDjrELjpo5aiZeMwF+yNnOs5KSvgAAAABJRU5ErkJggg==');
}

Split.js also works best when the elements are sized using border-box. The split class would have to be added manually to apply these styles:

.split {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
}

And for horizontal splits, make sure the layout allows elements (including gutters) to be displayed side-by-side. Floating the elements is one option:

.split,
.gutter.gutter-horizontal {
    float: left;
}

If you use floats, set the height of the elements including the gutters. The gutters will not be visible otherwise if the height is set to 0px.

.split,
.gutter.gutter-horizontal {
    height: 300px;
}

Overflow can be handled as well, to get scrolling within the elements:

.split {
    overflow-y: auto;
    overflow-x: hidden;
}

Browser Support

This library uses CSS calc(), CSS box-sizing and JS getBoundingClientRect(). These features are supported in the following browsers: | <img src="http://i.imgur.com/dJC1GUv.png" width="48px" height="48px" alt="Chrome logo"> | <img src="http://i.imgur.com/o1m5RcQ.png" width="48px" height="48px" alt="Firefox logo"> | <img src="http://i.imgur.com/8h3iz5H.png" width="48px" height="48px" alt="Internet Explorer logo"> | <img src="http://i.imgur.com/iQV4nmJ.png" width="48px" height="48px" alt="Opera logo"> | <img src="http://i.imgur.com/j3tgNKJ.png" width="48px" height="48px" alt="Safari logo"> | <img src="https://i.imgur.com/29eVTCg.png" height="28px" alt="Sauce Labs"> | | :-------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------- | | 22+ ✔ | 6+ ✔ | 9+ ✔ | 15+ ✔ | 6.2+ ✔ | Sponsored ✔ | Cross-browser Testing Platform and Open Source ❤️ Provided by Sauce Labs.

License

Copyright (c) 2022 Sam Fields Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SplitJS License

Copyright (c) 2019 Nathan Cahill Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.