The <ons-splitter-side> element is used as a child element of <ons-splitter>.
It will be displayed on either the left or right side of the <ons-splitter-content> element.
It supports two modes: collapsed and split. When it’s in collapsed mode it will be hidden from view and can be displayed when the user swipes the screen or taps a button. In split mode the element is always shown. It can be configured to automatically switch between the two modes depending on the screen size.
A menu can be added using the <ons-splitter>.
This element has several customization options. For small devices it can be used to create a swipeable menu but it’s also possible to customize it in order to automatically display a column layout on devices with larger screens.
To use it you need to add the <ons-splitter-content> and <ons-splitter-side> elements as children. The <ons-splitter-content> contains the main content and the <ons-splitter-side> is used for the menu.
The main content is contained inside the <ons-splitter-content>. Every Splitter must contains exactly one <ons-splitter-content>.
There are two ways to define the initial HTML. One way is to put the page inside the element:
<ons-splitter-content>
<ons-page>
...
</ons-page>
</ons-splitter-content>
Another way is to use the page attribute to load the content from a <template> element:
<template id="page.html">
</template>
...
<ons-splitter>
<ons-splitter-content page="page.html">
</ons-splitter-content>
</ons-splitter>
In order to change the content of the <ons-splitter-content> you can use the load(page, options) method:
var content = document.querySelector('ons-splitter-content');
// Switch to the Settings page.
content.load('settings.html');
Normally this method will be called when the user clicks on one of the items in the menu.
The <ons-splitter-side> supports several attributes that control the behavior of the menu.
This attribute must be defined to enable opening and closing the menu by swiping.
The menu supports two modes: “collapse” and “split” mode. When the menu is collapsed it will be hidden from view and only visible if the user swipes or the open() method is called.
In “split” mode the menu is displayed as a column on the side of the <ons-splitter-content> element.
The value of the collapse attribute defines when it should be in either mode conditionally. If you set the value to "portrait“ it will be collapsed when the device is in portrait mode. It also supports a media query.
You can try changing or removing the collapse attribute from the <ons-splitter-side> to see it in action.
This defines which side the menu is attached to. It supports the values "left" and "right". It’s possible to define one menu on each side of the screen.
Attributes are added directly to the element. You can do this in HTML or JS.
HTML: <ons-splitter-side someAttribute="true" anotherAttribute><ons-splitter-side>
JS: document.querySelector('ons-splitter-side').setAttribute('someAttribute', 'true')
| Name | Type | Description |
|---|---|---|
| animation |
String
default |
Specify the animation. Use one of overlay, push, reveal or default.
Optional.
|
| animation-options | Expression |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
Optional.
|
| open-threshold |
Number
0.3 |
Specify how much the menu needs to be swiped before opening. A value between 0 and 1.
Optional.
|
| collapse | String |
Specify the collapse behavior. Valid values are |
| swipe-target-width | String | The width of swipeable area calculated from the edge (in pixels). Use this to enable swipe only when the finger touch on the screen edge. Optional. |
| width | String |
Can be specified in either pixels or as a percentage, e.g. 90% or 200px.
Optional.
|
| side |
String
left |
Specify which side of the screen the <ons-splitter-side> element is located. Possible values are "left" and "right".
Optional.
|
| mode | String |
Current mode. Possible values are "collapse" or "split". This attribute is read only.
Optional.
|
| page | String | The URL of the menu page. Optional. Works only during initialization. |
| swipeable | Boolean | Whether to enable swipe interaction on collapse mode. Optional. |
Properties are accessed on the element through JS, and should be get and set directly. For example: document.querySelector('ons-splitter-side').animationOptions.
| Name | Description |
|---|---|
| animationOptions |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
|
| swipeable | Whether to enable swipe interaction on collapse mode. |
| page | Page location to load in the splitter side. |
| pageLoader | |
| mode | Current mode. Possible values are “split”, “collapse”, “closed”, “open” or “changing”. |
| onSwipe | Hook called whenever the user slides the splitter. It gets a decimal ratio (0-1) and an animationOptions object as arguments. |
| isOpen | Specifies whether the menu is opened. |
These methods are called directly on the DOM element. Get a reference to the element in JS, and the methods below will be available to call on it. For example: document.querySelector('ons-splitter-side').someMethod().
| Signature | Description |
|---|---|
| open([options]) | Open menu in collapse mode. |
| close([options]) | Close menu in collapse mode. |
| toggle([options]) | Opens if it’s closed. Closes if it’s open. |
| load(page, [options]) | Show the page specified in pageUrl in the right section |
Open menu in collapse mode.
Returns: Resolves to the splitter side element or false if not in collapse mode
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.callback | Function | This function will be called after the menu has been opened. |
Close menu in collapse mode.
Returns: Resolves to the splitter side element or false if not in collapse mode
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.callback | Function | This function will be called after the menu has been closed. |
Opens if it’s closed. Closes if it’s open.
Returns: Resolves to the splitter side element or false if not in collapse mode
| Name | Type | Description |
|---|---|---|
| options | Object |
Show the page specified in pageUrl in the right section
Returns: Resolves to the new page element
| Name | Type | Description |
|---|---|---|
| page | String |
Page URL. Can be either an HTML document or a <template>.
|
| options | Object | |
| options.callback | Function |
To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-splitter-side').addEventListener('modechange', function() { ... }).
Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).
| Name | Description |
|---|---|
| modechange | Fired just after the component’s mode changes. |
| preopen | Fired just before the sliding menu is opened. |
| postopen | Fired just after the sliding menu is opened. |
| preclose | Fired just before the sliding menu is closed. |
| postclose | Fired just after the sliding menu is closed. |
| swipe | Fired whenever the user slides the splitter. |
Fired just after the component’s mode changes.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.side | Object | Component object. |
| event.mode | String |
Returns the current mode. Can be either "collapse" or "split".
|
Fired just before the sliding menu is opened.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.cancel | Function | Call to cancel opening sliding menu. |
| event.side | Object | Component object. |
Fired just after the sliding menu is opened.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.side | Object | Component object. |
Fired just before the sliding menu is closed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.side | Object | Component object. |
| event.cancel | Function | Call to cancel opening sliding-menu. |
Fired just after the sliding menu is closed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.side | Object | Component object. |
Fired whenever the user slides the splitter.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.ratio | Object | Decimal ratio (0-1). |
| event.animationOptions | Object |
If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.
For bug reports and feature requests use our GitHub Issues page.