# Skeleton

- Entry point: `@koobiq/components/skeleton`
- NgModule: `KbqSkeletonModule`
- API: https://koobiq.io/api/skeleton.md
- Component tokens: https://koobiq.io/tokens/skeleton.md
- Page: https://koobiq.io/en/components/skeleton/overview

A skeleton is a temporary placeholder that previews the approximate shape of content while it loads. Use one when you know where the elements will appear.

## Basic block

The `<kbq-skeleton>` element is a basic rectangular block. Set its width and height with CSS. Combine several blocks into a custom composition when no preset fits.

[**Example: Skeleton basic block** (`skeleton-basic`)](https://koobiq.io/examples/skeleton-basic.md)

## Presets

Presets are ready-made placeholders for Koobiq components. Combine them to create a placeholder for an entire page.

### Typography

`KbqSkeletonTypography` creates a placeholder with line heights that match the selected [Koobiq typography style](https://koobiq.io/en/main/design-tokens.md). When there are several lines, their widths alternate randomly. The uneven right edge makes the placeholder look more like a paragraph.

[**Example: Skeleton typography preset** (`skeleton-typography`)](https://koobiq.io/examples/skeleton-typography.md)

### Separate elements

Placeholders for [buttons](https://koobiq.io/en/components/button.md), [badges](https://koobiq.io/en/components/badge.md), [tags](https://koobiq.io/en/components/tag.md), [icons](https://koobiq.io/en/components/icon.md), and [links](https://koobiq.io/en/components/link.md) match the height of their components. You can set their width with CSS.

[**Example: Skeleton element presets** (`skeleton-elements`)](https://koobiq.io/examples/skeleton-elements.md)

### Element groups

`KbqSkeletonGroup` displays a row of placeholders of the same type: buttons, badges, tags, icons, or links.

[**Example: Skeleton group preset** (`skeleton-group`)](https://koobiq.io/examples/skeleton-group.md)

### Parameter block

The `KbqSkeletonDl` component displays a placeholder for a set of parameters and their values.

[**Example: Skeleton description list preset** (`skeleton-dl`)](https://koobiq.io/examples/skeleton-dl.md)

### Table

While a [table](https://koobiq.io/en/components/table.md) or [AG Grid](https://koobiq.io/en/components/ag-grid.md) is loading, `KbqSkeletonTable` imitates its structure. You can set:

- the number of columns and the width of each column;
- the number of rows;
- whether to show checkboxes for selecting rows.

[**Example: Skeleton grid preset** (`skeleton-grid`)](https://koobiq.io/examples/skeleton-grid.md)

### Form field

`KbqSkeletonFormField` shows the label, field, and hint below it as one placeholder. The preset supports a multiline field and a label placed to its left.

[**Example: Skeleton form field preset** (`skeleton-form-field`)](https://koobiq.io/examples/skeleton-form-field.md)

### Expandable section

`KbqSkeletonAccordion` displays a placeholder for the [accordion](https://koobiq.io/en/components/accordion.md) component. The skeleton shows all groups collapsed.

[**Example: Skeleton accordion preset** (`skeleton-accordion`)](https://koobiq.io/examples/skeleton-accordion.md)

### Checkbox, radio button, and toggle

`KbqSkeletonCheckable` displays simplified placeholders for the label and a [checkbox](https://koobiq.io/en/components/checkbox.md), [radio button](https://koobiq.io/en/components/radio.md), or [toggle](https://koobiq.io/en/components/toggle.md). You can also show a hint.

[**Example: Skeleton checkable preset** (`skeleton-checkable`)](https://koobiq.io/examples/skeleton-checkable.md)

### Tabs

`KbqSkeletonTabs` creates a placeholder for tabs. You can customize the tab content. By default, it shows lines of text.

[**Example: Skeleton tabs preset** (`skeleton-tabs`)](https://koobiq.io/examples/skeleton-tabs.md)

### Hierarchical list

`KbqSkeletonTree` displays a placeholder for a hierarchical list. The second node is expanded to show the nested structure.

[**Example: Skeleton tree preset** (`skeleton-tree`)](https://koobiq.io/examples/skeleton-tree.md)

### Global configuration

Use `kbqSkeletonPresetsConfigurationProvider` to configure presets for the entire application or individual pages.

```ts
import { kbqSkeletonPresetsConfigurationProvider } from '@koobiq/components/skeleton';

@Component({
    providers: [
        kbqSkeletonPresetsConfigurationProvider({
            typographyLines: 1,
            dlRows: 3,
            tableRows: 3,
            tableColumns: 3,
            groupCount: 3,
            accordionRows: 3,
            checkableRows: 1,
            tabsCount: 3,
            tabsContentLines: 3,
            treeRows: 3,
            treeChildren: 3
        })
    ]
})
```

## Skeleton for a rendered element

The `kbqSkeleton` directive turns rendered elements and their content into placeholders that preserve their size.

[**Example: Skeleton directive** (`skeleton-directive`)](https://koobiq.io/examples/skeleton-directive.md)

## Usage examples

### Code block

While the [code block](https://koobiq.io/en/components/code-block.md) loads, a fixed-height skeleton appears in its place.

[**Example: Skeleton in place of a code block** (`skeleton-code-block`)](https://koobiq.io/examples/skeleton-code-block.md)

### Loading in parts

Data loads in parts. Placeholders disappear as the data updates.

[**Example: Skeleton in sidepanel** (`skeleton-in-sidepanel`)](https://koobiq.io/examples/skeleton-in-sidepanel.md)

## Guidelines

Use a skeleton when:

- The page or section structure is known in advance, and the data is loading for the first time.
- Loading takes a few seconds.

Do not use a skeleton in these cases:

- Loading takes less than 1 second; the skeleton can appear briefly and cause the interface to flicker.
- Use a [progress spinner](https://koobiq.io/en/components/progress-spinner.md) when an action is in progress, such as saving, deleting, or submitting a form.
- For long-running tasks, such as file conversion or data transfer, use a [progress bar](https://koobiq.io/en/components/progress-bar.md) or a [progress spinner](https://koobiq.io/en/components/progress-spinner.md).
- You can keep the previous content on screen during an update. Show the update state separately.
- Another indicator already shows that content is loading.
