Sidepanel — API

import { KbqSidepanelModule } from '@koobiq/components/sidepanel';

Components

KbqSidepanelContainerComponent

component

 @Component({ selector: 'kbq-sidepanel-container' })
class KbqSidepanelContainerComponent extends BasePortalOutlet {
    sidepanelConfig: KbqSidepanelConfig<any>;
    withIndent: boolean;
    id: string;
    readonly portalOutlet: Signal<CdkPortalOutlet>;
    readonly attachDomPortal: ((portal: DomPortal<HTMLElement>) => any) | null;
    attachComponentPortal<T>(
        portal: ComponentPortal<T>
    ): ComponentRef<T>;
    attachTemplatePortal<C>(
        portal: TemplatePortal<C>
    ): EmbeddedViewRef<C>;
    enter(): void;
    exit(): void;
    hasAttached(): boolean;
    attach<T>(portal: ComponentPortal<T>): ComponentRef<T>;
    attach<T>(portal: TemplatePortal<T>): EmbeddedViewRef<T>;
    attach(portal: any): any;
    detach(): void;
    dispose(): void;
}

withIndentCopy link to withIndentboolean: Whether the panel exposes the clickable indent strip of the sidepanel stacked underneath it.
idCopy link to idstring: ID for the container DOM element.
portalOutletCopy link to portalOutletSignal<CdkPortalOutlet>: The portal outlet inside of this container into which the content will be loaded.
attachComponentPortal()Copy link to attachComponentPortal()ComponentRef<T>: Attach a component portal as content to this sidepanel container.
attachTemplatePortal()Copy link to attachTemplatePortal()EmbeddedViewRef<C>: Attach a template portal as content to this sidepanel container.
enter()Copy link to enter()void: Begin animation of the sidepanel entrance into view.
exit()Copy link to exit()void: Begin animation of the sidepanel exiting from view.
hasAttached()Copy link to hasAttached()boolean: Whether this host has an attached portal.
detach()Copy link to detach()void: Detaches a previously attached portal.
dispose()Copy link to dispose()void: Permanently dispose of this portal host.

KbqSidepanelHeader

component

Header of a sidepanel.

 @Component({ selector: 'kbq-sidepanel-header' })
class KbqSidepanelHeader {
    readonly closeable = input<boolean>(false);
    readonly truncateText = input<boolean>(true);
}

closeableinputCopy link to closeableboolean: Add button for close sidepanel. Default false
truncateTextinputCopy link to truncateTextboolean: Enables text truncation. Default true
localeOverridesinputCopy link to localeOverridesKbqPartialLocaleData | undefined: Localized strings for this element and its subtree, keyed by locale section. Every key is optional at every depth.

Directives

KbqSidepanelActions

directive

Actions block of a sidepanel footer.

 @Directive({
    selector: 'kbq-sidepanel-actions, [kbq-sidepanel-actions], kbqSidepanelActions'
})
class KbqSidepanelActions {}

KbqSidepanelBody

directive

Scrollable content container of a sidepanel.

 @Directive({
    selector: 'kbq-sidepanel-body, [kbq-sidepanel-body], kbqSidepanelBody'
})
class KbqSidepanelBody {}

KbqSidepanelClose

directive

Button that will close the current sidepanel.

 @Directive({
    selector: 'button[kbq-sidepanel-close], button[kbqSidepanelClose]'
})
class KbqSidepanelClose {
    readonly sidepanelResult = input<any>(undefined, {
        alias: 'kbq-sidepanel-close'
    });
    readonly kbqSidepanelClose = input<any>();
    readonly sidepanelRef: KbqSidepanelRef<any, any>;
}

kbq-sidepanel-closeinputCopy link to kbq-sidepanel-closeany: Value handed to KbqSidepanelRef.close(), under the hyphenated spelling of the selector.
kbqSidepanelCloseinputCopy link to kbqSidepanelCloseany: The same value, under the camel-case spelling.

KbqSidepanelFooter

directive

Footer of a sidepanel.

 @Directive({
    selector: 'kbq-sidepanel-footer, [kbq-sidepanel-footer], kbqSidepanelFooter'
})
class KbqSidepanelFooter {}

Services

KbqSidepanelService

service

 @Injectable({ providedIn: 'root' })
class KbqSidepanelService {
    get openedSidepanels(): KbqSidepanelRef[];
    open<T, D = any>(
        componentOrTemplateRef: ComponentType<T> | TemplateRef<T>,
        config?: KbqSidepanelConfig<D>
    ): KbqSidepanelRef<T>;
    closeAll(): void;
    wasOpen(key: string): boolean;
    clearSavedState(key: string): void;
    getSidepanelById(id: string): KbqSidepanelRef | undefined;
}

openedSidepanels

KbqSidepanelRef[]

Keeps track of the currently-open sidepanels.

closeAll()

void

Closes all of the currently-open sidepanels.

Closing as a group is not recorded — see wasOpen().

wasOpen()

boolean

Whether the sidepanel persisted under key was open when it was last recorded, so the application can open it again:

if (sidepanel.wasOpen('filters')) this.openFilters();

A sidepanel cannot restore itself the way the components that persist do. It exists only while it is open, so at the point the state would be read there is nothing left to read it — and what to reopen is a component class or a TemplateRef and its data, none of which survives being written to storage. This service keeps the flag; the application keeps the rest.

What is recorded is a sidepanel opened and closed on its own. Closing a group — closeAll(), or this service being destroyed — leaves the flag alone, so a panel that was open when the page went away comes back whether the page was reloaded or navigated away from.

Reading claims the key: from here on KbqStateSavingService reports the entry as this service's rather than orphaned. It has to happen on read, because for a sidepanel that is not open this is the only call there is.

clearSavedState()

void

Removes what is persisted under key.

Persistence itself stays on: a sidepanel opened under that key again is recorded again.

getSidepanelById()

KbqSidepanelRef | undefined

Finds an open sidepanel by its id.

Parameters

idstring: ID to use when looking up the sidepanel.

Classes

KbqSidepanelConfig

class

 class KbqSidepanelConfig<D = any> {
    id?: string;
    stateSavingKey?: string;
    trapFocus?: boolean;
    trapFocusAutoCapture?: boolean;
    ariaLabel?: string;
    ariaLabelledBy?: string;
    data?: D | null;
    position?: KbqSidepanelPosition;
    size?: KbqSidepanelSize;
    hasBackdrop?: boolean;
    backdropClass?: string;
    disableClose?: boolean;
    overlayPanelClass?: string | string[];
    injector?: Injector;
    scrollStrategy?: () => ScrollStrategy;
}

idoptionalCopy link to idstring: ID for the sidepanel. If omitted, a unique one will be generated.
stateSavingKeyoptionalCopy link to stateSavingKeystring: Persists whether this sidepanel is open, under this key, so the application can bring it back on the next visit — see KbqSidepanelService.wasOpen().
Omit it and nothing is persisted. The key is the opt-in because there is nothing else stable to persist under: a sidepanel lives in an overlay, and id falls back to a counter that means something different on every load.
trapFocusoptionalCopy link to trapFocusboolean: Whether the focus trap is active. Defaults to whether the sidepanel has a backdrop.
trapFocusAutoCaptureoptionalCopy link to trapFocusAutoCaptureboolean: capture focus on initialization. This option sets cdkTrapFocusAutoCapture. Defaults to true.
ariaLabeloptionalCopy link to ariaLabelstring: Accessible name of the sidepanel, used when no kbq-sidepanel-header names it and no ariaLabelledBy is given.
ariaLabelledByoptionalCopy link to ariaLabelledBystring: Id of the element that labels the sidepanel. When omitted, kbq-sidepanel-header labels the sidepanel with its own title.
dataoptionalCopy link to dataD | null: Data being injected into the child component.
hasBackdropoptionalCopy link to hasBackdropboolean: Whether the sidepanel has a backdrop.
disableCloseoptionalCopy link to disableCloseboolean: Whether the user can use escape or clicking outside to close the sidepanel.
overlayPanelClassoptionalCopy link to overlayPanelClassstring | string[]: Custom class for the overlay pane.
injectoroptionalCopy link to injectorInjector: Injector used for the instantiation of the component to be attached. Allows to pass a custom injector to provide a dependency injection hierarchy for the sidepanel content.
scrollStrategyoptionalCopy link to scrollStrategy() => ScrollStrategy: Scroll strategy of the sidepanel overlay, resolved once when the sidepanel opens. Defaults to blocking the page scroll for sidepanels with a backdrop and to repositioning for the rest.

KbqSidepanelRef

class

 class KbqSidepanelRef<T = any, R = any> {
    readonly id: string;
    readonly bodyOverflow: WritableSignal<KbqOverflowShadowState>;
    instance: T;
    readonly containerInstance: KbqSidepanelContainerComponent;
    readonly overlayRef: OverlayRef;
    readonly config: KbqSidepanelConfig<any>;
    constructor(
        containerInstance: KbqSidepanelContainerComponent,
        overlayRef: OverlayRef,
        config: KbqSidepanelConfig<any>
    );
    close(result?: R): void;
    beforeClosed(): Observable<void>;
    afterClosed(): Observable<R | undefined>;
    afterOpened(): Observable<void>;
}

bodyOverflowCopy link to bodyOverflowWritableSignal<KbqOverflowShadowState>: Vertical scroll overflow state of the sidepanel body. Updated on scroll and used for visual adjustments.
instanceCopy link to instanceT: Instance of the component making up the content of the sidepanel.
beforeClosed()Copy link to beforeClosed()Observable<void>: Gets an observable that is notified when the sidepanel is started closing.
afterClosed()Copy link to afterClosed()Observable<R | undefined>: Gets an observable that is notified when the sidepanel is finished closing.
afterOpened()Copy link to afterOpened()Observable<void>: Gets an observable that is notified when the sidepanel has opened and appeared.

Types

KbqSidepanelState

interface

The persisted state of a sidepanel — whether it was open.

 interface KbqSidepanelState {
    opened: boolean;
}

Enums

KbqSidepanelPosition

enum

 enum KbqSidepanelPosition {
    Right = 'right',
    Left = 'left',
    Top = 'top',
    Bottom = 'bottom'
}

KbqSidepanelSize

enum

 enum KbqSidepanelSize {
    Small = 'small',
    Medium = 'medium',
    Large = 'large'
}

Constants

KBQ_SIDEPANEL_DATA

const

Injection token that can be used to access the data that was passed in to a sidepanel.

const KBQ_SIDEPANEL_DATA: InjectionToken<any>;

KBQ_SIDEPANEL_DEFAULT_OPTIONS

const

Injection token that can be used to specify default sidepanel options.

const KBQ_SIDEPANEL_DEFAULT_OPTIONS: InjectionToken<KbqSidepanelConfig>;

KBQ_SIDEPANEL_WITH_INDENT

const

const KBQ_SIDEPANEL_WITH_INDENT: InjectionToken<boolean>;

If you found a mistake or want to improve the article, create an issue on GitHub.