Svelte_sidebar NPM

Svelte Sidebar

npm NPM Bundlephobia

Sidebar navigation component written in svelte and compiled to an ES module of 8kb.

What it is

This sidebar navigation for web application replicates the experience of browsing the file tree in a code editor. The benefit is that the user can understand the application's information architecture (IA) at first glance, and can quickly jump between different hierarchy levels. The UI pattern goes well with complex web applications with a lot of nested routes, especially for applications where the user can create data entries (e.g. where multiple users create projects, each of which is composed of multiple screens).

Features

Usable in any web-app where the navigation routes are known / computable, as the sidebar is an ES module.
Semantic, accessible DOM. Navigation is entirely possible with the keyboard. Animations are disabled when prefers-reduced-motion is set.
The navigation hierarchy can be nested as deeply as required. Navigation links with sub-links are collapsible groups.
Automatically un-collapses the active part of the navigation hierarchy and scrolls it into the viewport. Parent navigation items of the active navigation item are also highlighted compared to inactive navigation items.
Every navigation link can be disabled.
Just enough configuration possibilities for re-usability: - By default, the regular browser navigation occurs when the user clicks on a link (or presses Enter). A function can be passed as property to interrupt the regular navigation to handle navigation on the client side. - Themeable: Colors (including hover styles), font sizing, and the minimum and maximum width (depending on the length of the names of navigation links).
h(n) performance when matching the active route in the navigation hierarchy, where n signifies the count of navigation links.

Installation

Without installation from skypack:

	```js
	import Sidebar from 'https://cdn.skypack.dev/svelte_sidebar'
	```

Yarn package manager: yarn add svelte_sidebar
NPM package manager: npm install --save svelte_sidebar

Usage

On any web site / app as ES module

<!-- index.html -->
<div id="app"></div>

<script type="module">
import Sidebar from 'https://cdn.skypack.dev/svelte_sidebar'

  const props = {
    routes: [
		{ "name": "Playground", "route": "/" },
		{ "name": "Readme", "route": "/readme", "childRoutes": [
			{ "name": "What it is", "route": "/readme#what-it-is" }
			]
		}
	],
    activeUrl: '/'
  }

  new Sidebar({target: document.querySelector('#app'), props})
</script>

In a svelte web app

// App.svelte
import Sidebar from 'svelte_sidebar' // or from skypack

const props = {...}

<Sidebar {...props} />

Sidebar component properties

property name	required	default	description	value type	example value
`activeUrl`	no	`null`	The URL that is active in the application.	string	`'https://sidebar.schneiders.space'`. In a SPA, one would pass the string in from the router, or `window.location.path`
`routes`	no	`[]`	This property contains the navigation hierarchy rendered by the sidebar. It's made up from an array of objects mapping URLs to navigation link names and defining the nesting of sub-routes. Not passing values is possible and could e.g. be used while fetching the data required to compute the menu hierarchy.	array, as specified below	see `src/exampleConfig/routes.js`
`onLinkClick`	no	`null`	Function that is executed when the user selects a navigation link. Prevents the regular navigation event. Therefore useful in applications with client side routing.	function receiving the event	`(event) => alert(event.target.href)`
`theme`	no	see `defaultTheme` in `src/components/Sidebar/Sidebar.svelte`	Allows to customize the most important styles.	object, as described below	`{ backgroundColor_nav: '###ccc' }`
`open`	no	true	Allows to customize whether the navigation sidebar is open or horizontally minimized.	boolean	`true`. To collapse the sidebar by default on smaller viewports, the result of an expression like `window.innerWidth < 720px` could be passed.
`transitionEnabled`	no	`true`	Whether the route's content will transition in when being displayed. The default is `true`. `False` is less playful, and always used when `prefers-reduced-motion` is enabled.	`boolean`

The playground allows to play around with every property. It shows the sidebar on the left, and the component usage on the right. It's therefore the quickest way to find out how to use the component, and to see whether it covers your needs.

The `routes` array

As specified above, routes is an array of navigation route objects. Every one of those objects can have the attributes shown below (others are ignored):

{
	name: 'Products',
	route: '/products',
	disabled: true, /* optional */
	collapseTree: true, /* optional */
	childRoutes: [] /* optional */
}

Following the description of a route object's attributes:

attribute name	required	default	description	value type
´name´	yes	-	The name under which the navigation link will be shown in the navigation hierarchy	`string`
´route´	yes	-	The navigation links' URL	`string`
`disabled`	no	`false`	Whether the link is selectable by the user. The default is `false`. `True` can make sense, e.g. if the user is not authorized to access a part of the application. If the route has child routes, the navigation link group can not be uncollapsed by the user.	`boolean`
`collapseTree`	no	`false`	Allows to customize whether child routes are shown or vertically collapsed by default.	boolean
`childRoutes`	no	`[]`	An array of more route objects. As every route object can have child routes, there's theoretically no limit to the depth of the navigation hierarchy.	`array`

The `theme` property

The theme property object takes the following attributes with matching CSS values:

attribute name	default	description
`backgroundColor_linkActive`	#F4442E	Background color of the active link in the navigation hierarchy.
`backgroundColor_nav`	#555B6E	Background color of the whole navigation sidebar.
`color_link`	#F7F7F2	Text color of a navigation link in default state.
`color_linkHover`	#FCA311	Text color of a navigation link when it's hovered upon or focused with the keyboard.
`fontSize`	1.2rem	Font size of navigation links.
`maxWidth_nav`	20vw	The maximum width of the navigation sidebar. Navigation links' name will wrap into multiple lines, if their width in addition to their nesting would surpass `maxWidth_nav`.
`minWidth_nav`	320px	Minimum width of the navigation sidebar. `minWidth_nav` is stronger than `maxWidth_nav`. If min width is larger than max width, min width will define the applied style.
`opacity_linkDisabled`	0.5	Text opacity of navigation links, that have been specified to be disabled.
`opacity_linkInactive`	0.75	Text opacity of navigation links that are not part of the navigation hierarchy that contains the active link.

The property names are CSS custom properties attached to the sidebar element.

Slots

The sidebar can also be passed children that are placed in pre-defined slots in the sidebar. There's a slot named header that is rendered above all navigation links (e.g. for company name and logo), and one below all navigation links called footer. On the playground, this slot is used to render the theme switcher.