API REFERENCE

EdgeSidebar Builder

create

Before you register a config, you need to create an edge sidebar with an id and props.

Interface

type create = (
  sidebarId: string,
  props: { anchor: 'left' | 'right' }
) => IEdgeSidebarRegistry;

Usage

scheme.configureEdgeSidebar(builder => {
  builder.create('primarySidebar', { anchor: 'left' }); // this will return a registry
});

After you calling this function, you can register a config by chaining register methods. There are 3 register methods that you can use

registerTemporaryConfig

Interface

type registerTemporaryConfig = (
  breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl',
  config: {
    width: number(px) | 'auto' | 'rem' | 'em' | 'x%'
  }
) => IEdgeSidebarRegistry;

Usage

Because registerTemporaryConfig return the same registry, you can also chain another register fn to configure other breakpoints as many as you like. However, if there are duplicate breakpoint, the latest call will override because builder store it as object under the hood. Mostly, this variant is for xs breakpoint.

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerTemporaryConfig('xs', {
      width: 'auto', // depends on sidebar content
    });
  // you can register more breakpoint, if needed.
});

registerPermanentConfig

Interface

type registerPermanentConfig = (
  breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl',
  config: {
    width: number(px) | 'rem' | 'em' | 'x%', // auto is not allowed for this variant
    collapsible: boolean,
    collapsedWidth?: number(px) | 'rem' | 'em' | 'x%',
    autoExpanded?: boolean,
    headerMagnetEnabled?: boolean
  }
) => IEdgeSidebarRegistry;

Usage

Mostly, this variant is for md breakpoint up because it permanently stay on the page.

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerPermanentConfig('md', {
      width: 256, // recommended width
      collapsible: true,
      collapsedWidth: 64,
      autoExpanded: true,
      headerMagnetEnabled: true,
    });
  // you can register more breakpoint, if needed.
});

Config

  • width
    • type : number(px) | ‘rem’ | ‘em’ | ‘x%’
    • required : yes
    • description : css width of the Paper component inside Drawer or SwipeableDrawer
  • collapsible
    • type : boolean
    • default : false
    • description : to make the sidebar collapsible and affect display property of CollapseBtn
  • collapsedWidth
    • type : number(px) | 'px' | 'rem' | 'em'
    • default : 64
    • description : width of the sidebar if collapsed state is true
  • autoExpanded
    • type : boolean
    • default : false
    • description : sidebar will expand automatically on mouseover if collapsed state is true
  • headerMagnetEnabled
    • type : boolean
    • default : false
    • description : sidebar content will snap to top when clipped header’s is set to relative and user scroll down to prevent empty space at the top of sidebar.

registerPersistentConfig

Interface

type registerPersistentConfig = (
  breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl',
  config: {
    width: number(px) | 'rem' | 'em' | 'x%', // auto is not allowed for this variant
    collapsible: boolean,
    collapsedWidth?: number(px) | 'rem' | 'em' | 'x%',
    autoExpanded: boolean,
    headerMagnetEnabled?: boolean,
    persistentBehavior?: 'fit' | 'flexible' | 'none' | Dictionary<'fit' | 'flexible' | 'none'>
  }
) => IEdgeSidebarRegistry;

Usage

Mostly, this variant is for sm breakpoint up because it can be hidden and does not have overlay.

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerPersistentConfig('sm', {
      width: 256, // recommended width
      collapsible: true,
      collapsedWidth: 64,
      autoExpanded: true,
      headerMagnetEnabled: true,
      persistentBehavior: 'fit'
    });
  // you can register more breakpoint, if needed.
});

Config

  • width, collapsible, collapsedWidth, autoExpanded and headerMagnetEnabled is the same as permanentConfig
  • persistentBehavior
    • type : 'fit' | 'flexible' | 'none' | Dictionary<'fit' | 'flexible' | 'none'>
    • default : 'none'
    • description : the behavior that other components will interact with this sidebar when it is open
      - fit : the object is pushed and its width is fit to browser
      - flexible : the object is pushed but its width remains the same
      - none : the object is not pushed and width remains the same
    • example : you can control this behavior for specific object (unclipped header, content, footer will have be affected by this variant)
    persistentBehavior: { appHeader: 'fit', content: 'flexible', footer: 'none' }

hide

You can hide a sidebar at specific breakpoints by using this function. It accepts 2 parameters, sidebarId and breakpoints.

Interface

type hide = (
  sidebarId: string,
  breakpoints: boolean | ('xs' | 'sm' | 'md' | 'lg' | 'xl')[]
) => void;

Usage

When you register a config at some breakpoint, it will affect bigger breakpoints with the same config if you don’t specify other config to override. In some case you want to hide it in some breakpoints, that’s when this function is useful. Take below config example, the config defined in xs will also have an effect for sm. Then in md, permanent config will take place up to xl. If I don’t want this sidebar to show in sm or xl, I can do that by calling hide with the breakpoints I want

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    .registerTemporaryConfig('xs', {
      width: 'auto', // depends on sidebar content
    })
    .registerPermanentConfig('md', {
      width: 256, // recommended width
      collapsible: true,
      collapsedWidth: 64,
      headerMagnetEnabled: true,
    });
  
  // do not chain from register
  // hide is a method of builder
  builder.hide('primarySidebar', ["sm", "xl"])
});

Or if you want to hide at all breakpoints, you can specify breakpoints as true

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
  // ...register config  

  // do not chain from register
  // hide is a method of builder
  builder.hide('primarySidebar', true)
});

At this point, you might ask why do I create the sidebar if I want to hide it at for all breakpoints? Good question, there are some use cases where you want to hide the sidebar at specific url, ex. homepage. You want to show full content banner, company info and navigation in header without sidebar. However, when user go to other routes, you want them to see the sidebar to interact with more actions. See example


update

This function is for updating config at client side. Ex. update sidebar’s width according to some condition.

Interface

type update = (
  updater: (config: MapBreakpoint<EdgeSidebarConfig>) => void
) => void;

Usage Example

scheme.configureEdgeSidebar(builder => {
  builder
    .create('primarySidebar', { anchor: 'left' })
    // ...register part
  
  builder.update('primarySidebar', config => {
    if (someParameter) {
      config.md.width = 300
    }  
    if (location.pathname === '/some-url') {
      config.md.persistentBehavior = 'none'
    } 
  })
});