import { KbqTabsModule } from '@koobiq/components/tabs';

KbqTab

componentCopy link to KbqTab
@Component({ selector: 'kbq-tab', exportAs: 'kbqTab' })
class KbqTab {
    tooltipTitle = input<string | undefined>();
    disabled = input<boolean | undefined>();
    readonly tooltipPlacement = input<KbqPopUpPlacementValues>(
        PopUpPlacements.Right
    );
    readonly textLabel = input<string>('', { alias: 'label' });
    readonly empty = input<boolean>(false);
    readonly tabId = input<string>();
    templateLabel: KbqTabLabel;
    readonly explicitContent: Signal<TemplateRef<any> | undefined>;
    readonly implicitContent: Signal<TemplateRef<any>>;
    get iconOnlyLabel(): boolean;
    readonly stateChanges: Subject<void>;
    position: number | null;
    origin: number | null;
    isActive: boolean;
    get isOverflown(): boolean;
    overflowTooltipTitle: string;
}
disabledinputCopy link to disabledboolean | undefined

Whether the tab is disabled: it cannot be selected and has no interactive states.

tooltipPlacementinputCopy link to tooltipPlacementKbqPopUpPlacementValues

Placement of the tooltip shown for a truncated or empty label.

labelinputCopy link to labelstring

Plain text label for the tab, used when there is no template label.

templateLabelCopy link to templateLabelKbqTabLabel

The label template of the tab: the kbqTabLabel in its content, or else the one assigned in code.

explicitContentCopy link to explicitContentSignal<TemplateRef<any> | undefined>

Template provided in the tab content that will be used if present, used to enable lazy-loading

implicitContentCopy link to implicitContentSignal<TemplateRef<any>>

Template inside the KbqTab view that contains an <ng-content>.

iconOnlyLabelCopy link to iconOnlyLabelboolean

Whether the tab label contains only an icon (no text).

stateChangesCopy link to stateChangesSubject<void>

Emits whenever the internal state of the tab changes.

positionCopy link to positionnumber | null

The relatively indexed position where 0 represents the center, negative is left, and positive represents the right.

originCopy link to originnumber | null

The initial relatively index origin of the tab if it was created and selected after there was already a selected tab. Provides context of what position the tab should originate from.

isActiveCopy link to isActiveboolean

Whether the tab is currently active. A template that reads it is updated when it changes.

KbqTabGroup

componentCopy link to KbqTabGroup

Tab-group component. Supports basic tab pairs (label + content) and includes keyboard navigation.

@Component({ selector: 'kbq-tab-group', exportAs: 'kbqTabGroup' })
class KbqTabGroup {
    readonly transparent = input<boolean>(false);
    readonly onSurface = input<boolean>(false);
    readonly underlined = input<boolean>(false);
    readonly vertical = input<boolean>(false);
    readonly dynamicHeight = input<boolean>(false);
    selectedIndex = model<number | undefined>();
    activeTab = model<KbqTabSelectBy | null | undefined>();
    headerPosition = input<KbqTabHeaderPosition | undefined>();
    animationDuration = input<string | undefined>();
    readonly focusChange = output<KbqTabChangeEvent>();
    readonly animationDone = output<void>();
    readonly selectedTabChange = output<KbqTabChangeEvent>();
    get tabs(): QueryList<KbqTab>;
    readonly tabBodyWrapper: Signal<ElementRef<any>>;
    readonly tabHeader: Signal<KbqTabHeader>;
    get hasSavedState(): boolean;
    focusChanged(index: number): void;
    getTabLabelId(i: number): string;
    getTabContentId(i: number): string;
    setTabBodyWrapperHeight(tabHeight: number): void;
    removeTabBodyWrapperHeight(): void;
    handleClick(
        tab: KbqTab,
        tabHeader: KbqTabHeader,
        index: number
    ): void;
    getTabIndex(
        tab: KbqTab,
        tabHeader: KbqTabHeader,
        index: number
    ): number;
    onSelectFocusedIndex($event: number): void;
    saveState(): void;
    clearSavedState(): void;
}
transparentinputCopy link to transparentboolean

Whether the tab strip background should be transparent.

onSurfaceinputCopy link to onSurfaceboolean

Whether the group is rendered on a surface rather than on the page background.

underlinedinputCopy link to underlinedboolean

Whether the selected tab is marked with an underline instead of a filled background.

verticalinputCopy link to verticalboolean

Whether the tab strip is laid out vertically, alongside the content instead of above it.

dynamicHeightinputCopy link to dynamicHeightboolean

Whether the tab group should grow to the size of the active tab.

selectedIndexmodelCopy link to selectedIndexnumber | undefined

The index of the active tab.

headerPositioninputCopy link to headerPositionKbqTabHeaderPosition | undefined

Position of the tab header.

animationDurationinputCopy link to animationDurationstring | undefined

Duration for the tab animation. Must be a valid CSS value (e.g. 600ms).

useStateSavinginputCopy link to useStateSavingboolean

Whether the component remembers its state across reloads and restores it on the next render. Defaults to true, or to whatever KBQ_STATE_SAVING_ENABLED is provided as.

stateSavingKeyinputCopy link to stateSavingKeystring

The key the state is persisted under. While it is empty the key is derived from where the component sits in the document, which moves when the surrounding markup is restructured — an id on the component or any ancestor pins it just as well as this input does.

focusChangeoutputCopy link to focusChangeKbqTabChangeEvent

Event emitted when focus has changed within a tab group.

animationDoneoutputCopy link to animationDonevoid

Event emitted when the body animation has completed

selectedTabChangeoutputCopy link to selectedTabChangeKbqTabChangeEvent

Event emitted when the tab selection has changed.

tabsCopy link to tabsQueryList<KbqTab>

The tabs of the group.

hasSavedStateCopy link to hasSavedStateboolean

Whether state is currently persisted for this tab group — restored on init, or written since. Always false while useStateSaving is unset, and false again after clearSavedState().

getTabLabelId()Copy link to getTabLabelId()string

Returns a unique id for each tab label element

getTabContentId()Copy link to getTabContentId()string

Returns a unique id for each tab content element

setTabBodyWrapperHeight()Copy link to setTabBodyWrapperHeight()void

Sets the height of the body wrapper to the height of the activating tab if dynamic height property is true.

removeTabBodyWrapperHeight()Copy link to removeTabBodyWrapperHeight()void

Removes the height of the tab body wrapper.

handleClick()Copy link to handleClick()void

Handle click events, setting new selected index if appropriate.

getTabIndex()Copy link to getTabIndex()number

Retrieves the tabindex for the tab. The single 0 follows the header's focus position rather than the selection, so that a disabled selected tab cannot take the whole strip out of the tab order — a disabled tab is -1, never absent, so it stays a roving-tabindex participant.

saveState()Copy link to saveState()void

Persists which tab is selected.

Called for every selection a user makes. Both the tab's tabId and its position are stored: the tabId is the only one that survives the tabs being reordered, and the position is all there is when the tabs carry none.

clearSavedState()Copy link to clearSavedState()void

Removes the state persisted for this tab group.

Persistence itself stays on — the next selection is written again. Unset useStateSaving to stop it.

KbqTabNavBar

componentCopy link to KbqTabNavBar

Navigation component matching the styles of the tab group header.

@Component({
    selector: '[kbqTabNavBar], [kbq-tab-nav-bar]',
    exportAs: 'kbqTabNavBar'
})
class KbqTabNavBar extends KbqPaginatedTabHeader {
    readonly transparent = input<boolean>(false);
    readonly onSurface = input<boolean>(false);
    readonly underlined = input<boolean>(false);
    readonly tabNavPanel = input<KbqTabNavPanel>();
    selectedIndex = input<number | undefined>();
    disablePagination = input<boolean | undefined>();
    vertical = input<boolean | undefined>();
    get tabListContainer(): ElementRef;
    get tabList(): ElementRef;
    get nextPaginator(): ElementRef<HTMLElement>;
    get previousPaginator(): ElementRef<HTMLElement>;
    get items(): QueryList<KbqTabLink>;
    get role(): string | null;
    focusIndex: number;
    readonly selectFocusedIndex: EventEmitter<number>;
    readonly indexFocused: EventEmitter<number>;
    showPaginationControls: boolean;
    disableScrollAfter: boolean;
    disableScrollBefore: boolean;
    readonly elementRef: ElementRef<HTMLElement>;
    updateActiveLink(): void;
    handleKeydown(event: KeyboardEvent): void;
    onContentChanges(): void;
    updatePagination(): void;
    isValidIndex(index: number): boolean;
    setTabFocus(tabIndex: number): void;
    getLayoutDirection(): Direction;
    scrollHeader(direction: ScrollDirection): void;
    handlePaginatorClick(direction: ScrollDirection): void;
    checkPaginationEnabled(): void;
    stopInterval(): void;
    handlePaginatorPress(
        direction: ScrollDirection,
        mouseEvent?: MouseEvent
    ): void;
}
transparentinputCopy link to transparentboolean

Whether the nav bar background should be transparent.

underlinedinputCopy link to underlinedboolean

Whether the nav bar should be underlined.

tabNavPanelinputCopy link to tabNavPanelKbqTabNavPanel

Associated tab panel controlled by the nav bar.

selectedIndexinputCopy link to selectedIndexnumber | undefined

The index of the active tab.

disablePaginationinputCopy link to disablePaginationboolean | undefined

Whether pagination should be disabled. This can be used to avoid unnecessary layout recalculations if it's known that pagination won't be required.

A vertical header never paginates, so vertical forces this on without overwriting the value the consumer set — turning vertical back off restores it.

verticalinputCopy link to verticalboolean | undefined

Whether the tabs should be displayed vertically.

tabListContainerCopy link to tabListContainerElementRef

The scroll container of the tab links.

tabListCopy link to tabListElementRef

The element that holds the tab links.

nextPaginatorCopy link to nextPaginatorElementRef<HTMLElement>

The pagination arrow towards the end of the tab list.

previousPaginatorCopy link to previousPaginatorElementRef<HTMLElement>

The pagination arrow towards the beginning of the tab list.

itemsCopy link to itemsQueryList<KbqTabLink>

The tab links of the nav bar.

focusIndexCopy link to focusIndexnumber

Tracks which element has focus; used for keyboard navigation

selectFocusedIndexCopy link to selectFocusedIndexEventEmitter<number>

Event emitted when the option is selected.

indexFocusedCopy link to indexFocusedEventEmitter<number>

Event emitted when a label is focused.

showPaginationControlsCopy link to showPaginationControlsboolean

Whether the controls for pagination should be displayed

disableScrollAfterCopy link to disableScrollAfterboolean

Whether the tab list can be scrolled more towards the end of the tab label list.

disableScrollBeforeCopy link to disableScrollBeforeboolean

Whether the tab list can be scrolled more towards the beginning of the tab label list.

onContentChanges()Copy link to onContentChanges()void

Callback for when the MutationObserver detects that the content has changed.

updatePagination()Copy link to updatePagination()void

Updates the view whether pagination should be enabled or not.

WARNING: Calling this method can be very costly in terms of performance. It should be called as infrequently as possible from outside of the Tabs component as it causes a reflow of the page.

isValidIndex()Copy link to isValidIndex()boolean

Determines if an index is valid. If the tabs are not ready yet, we assume that the user is providing a valid index and return true.

setTabFocus()Copy link to setTabFocus()void

Sets focus on the HTML element for the label wrapper and scrolls it into the view if scrolling is enabled.

getLayoutDirection()Copy link to getLayoutDirection()Direction

The layout direction of the containing app.

scrollHeader()Copy link to scrollHeader()void

Moves the tab list in the 'before' or 'after' direction (towards the beginning of the list or the end of the list, respectively).

This is an expensive call that forces a layout reflow to compute box and scroll metrics and should be called sparingly.

handlePaginatorClick()Copy link to handlePaginatorClick()void

Handles click events on the pagination arrows.

checkPaginationEnabled()Copy link to checkPaginationEnabled()void

Evaluate whether the pagination controls should be displayed. If the scroll width of the tab list is wider than the size of the header container, then the pagination controls should be shown.

This is an expensive call that forces a layout reflow to compute box and scroll metrics and should be called sparingly.

stopInterval()Copy link to stopInterval()void

Stops the currently-running paginator interval.

handlePaginatorPress()Copy link to handlePaginatorPress()void

Handles the user pressing down on one of the paginators. Starts scrolling the header after a certain amount of time.

Parameters
directionScrollDirection

In which direction the paginator should be scrolled.

KbqAlignTabsCenterCssStyler

directiveCopy link to KbqAlignTabsCenterCssStyler
@Directive({
    selector: 'kbq-tab-group[kbq-align-tabs-center], [kbq-tab-nav-bar][kbq-align-tabs-center], [kbqTabNavBar][kbq-align-tabs-center]'
})
class KbqAlignTabsCenterCssStyler {}

KbqAlignTabsEndCssStyler

directiveCopy link to KbqAlignTabsEndCssStyler
@Directive({
    selector: 'kbq-tab-group[kbq-align-tabs-end], [kbq-tab-nav-bar][kbq-align-tabs-end], [kbqTabNavBar][kbq-align-tabs-end]'
})
class KbqAlignTabsEndCssStyler {}

KbqStretchTabsCssStyler

directiveCopy link to KbqStretchTabsCssStyler
@Directive({
    selector: 'kbq-tab-group[kbq-stretch-tabs], [kbq-tab-nav-bar][kbq-stretch-tabs], [kbqTabNavBar][kbq-stretch-tabs]'
})
class KbqStretchTabsCssStyler {}

KbqTabContent

directiveCopy link to KbqTabContent

Decorates the ng-template tags and reads out the template from it.

@Directive({ selector: '[kbqTabContent]' })
class KbqTabContent {
    template: TemplateRef<any>;
}

KbqTabLabel

directiveCopy link to KbqTabLabel

Used to flag tab labels for use with the portal directive

@Directive({ selector: '[kbq-tab-label], [kbqTabLabel]' })
class KbqTabLabel extends CdkPortal {
    readonly iconOnly = input<boolean>(false);
    templateRef: TemplateRef<C>;
    viewContainerRef: ViewContainerRef;
    context?: C;
    injector?: Injector;
    get origin(): ElementRef<any>;
    get isAttached(): boolean;
    attach(host: PortalOutlet, context?: C): EmbeddedViewRef<C>;
    detach(): void;
    setAttachedHost(host: PortalOutlet | null): void;
}
iconOnlyinputCopy link to iconOnlyboolean

Whether the tab contains only an icon without a label.

templateRefCopy link to templateRefTemplateRef<C>

The embedded template that will be used to instantiate an embedded View in the host.

viewContainerRefCopy link to viewContainerRefViewContainerRef

Reference to the ViewContainer into which the template will be stamped out.

contextoptionalCopy link to contextC

Contextual data to be passed in to the embedded view.

injectoroptionalCopy link to injectorInjector

The injector to use for the embedded view.

isAttachedCopy link to isAttachedboolean

Whether this portal is attached to a host.

attach()Copy link to attach()EmbeddedViewRef<C>

Attach the portal to the provided PortalOutlet. When a context is provided it will override the context property of the TemplatePortal instance.

setAttachedHost()Copy link to setAttachedHost()void

Sets the PortalOutlet reference without performing attach(). This is used directly by the PortalOutlet when it is performing an attach() or detach().

KbqTabLink

directiveCopy link to KbqTabLink

Link inside of a KbqTabNavBar.

@Directive({ selector: '[kbqTabLink], [kbq-tab-link]', exportAs: 'kbqTabLink' })
class KbqTabLink {
    id = input<string | undefined>();
    active = input<boolean | undefined>();
    disabled = input<boolean | undefined>();
    get vertical(): boolean;
    get underlined(): boolean;
    readonly elementRef: ElementRef<HTMLElement>;
    focus(): void;
}

KbqTabNavPanel

directiveCopy link to KbqTabNavPanel

Tab panel component associated with KbqTabNav.

@Directive({ selector: '[kbqTabNavPanel]', exportAs: 'kbqTabNavPanel' })
class KbqTabNavPanel {
    readonly id = input<string>(`kbq-tab-nav-panel-${nextUniqueId++}`);
    activeTabId?: string;
}
idinputCopy link to idstring

Unique id for the tab panel.

activeTabIdoptionalCopy link to activeTabIdstring

Id of the active tab in the nav bar.

KbqVerticalTabsCssStyler

directiveDeprecatedCopy link to KbqVerticalTabsCssStyler

No-op. The vertical layout class is bound from KbqTabGroup/KbqTabNavBar themselves, so it follows the vertical value instead of merely the presence of the attribute. Will be removed in a future major version — stop importing it.

@Directive({
    selector: 'kbq-tab-group[vertical], [kbq-tab-nav-bar][vertical], [kbqTabNavBar][vertical]'
})
class KbqVerticalTabsCssStyler {}

KbqTabChangeEvent

classCopy link to KbqTabChangeEvent

A simple change event emitted on focus or selection changes.

class KbqTabChangeEvent {
    index: number;
    tab: KbqTab;
}
indexCopy link to indexnumber

Index of the currently-selected tab.

tabCopy link to tabKbqTab

Reference to the currently-selected tab.

KbqPaginatedTabHeaderItem

typeCopy link to KbqPaginatedTabHeaderItem

Item inside a paginated tab header.

type KbqPaginatedTabHeaderItem = FocusableOption & {
    elementRef: ElementRef;
};

KbqTabBodyPositionState

typeCopy link to KbqTabBodyPositionState

These position states are used internally as the translation states of the tab body. Setting the position state to left, right, or center will transition the tab body from its current position to its respective state. If there is not current position (void, in the case of a new tab body), then there will be no transition to its state.

In the case of a new tab body that should immediately be centered with an animating transition, then left-origin-center or right-origin-center can be used, which will use left or right as its pseudo-prior state.

type KbqTabBodyPositionState = 'left' | 'center' | 'right' | 'left-origin-center' | 'right-origin-center';

KbqTabHeaderPosition

typeCopy link to KbqTabHeaderPosition

Possible positions for the tab header.

type KbqTabHeaderPosition = 'above' | 'below';

KbqTabsConfig

interfaceCopy link to KbqTabsConfig

Object that can be used to configure the default options for the tabs module.

interface KbqTabsConfig {
    animationDuration?: string;
}
animationDurationoptionalCopy link to animationDurationstring

Duration for the tab animation. Must be a valid CSS value (e.g. 600ms).

KbqTabSelectBy

typeCopy link to KbqTabSelectBy
type KbqTabSelectBy = string | number | ((tabs: KbqTab[]) => KbqTab | null);

KbqTabsState

interfaceCopy link to KbqTabsState

The persisted state of a tab group — which tab was selected.

Both are stored: tabId is the only identifier that survives a reordering, and index is all there is when the tabs carry no tabId.

interface KbqTabsState {
    tabId: string | null;
    index: number;
}

ScrollDirection

typeCopy link to ScrollDirection

The directions that scrolling can go in when the header's tabs exceed the header width. 'After' will scroll the header towards the end of the tabs list and 'before' will scroll towards the beginning of the list.

type ScrollDirection = 'after' | 'before';

KBQ_TAB_LABEL

constCopy link to KBQ_TAB_LABEL
const KBQ_TAB_LABEL: InjectionToken<KbqTabLabel>;

KBQ_TABS_CONFIG

constCopy link to KBQ_TABS_CONFIG

Injection token that can be used to provide the default options the tabs module.

const KBQ_TABS_CONFIG: InjectionToken<KbqTabsConfig>;
Suggestions for improvement
If you found a mistake or want to improve the article, create an issue on GitHub.