# How to Configure Sidebar and Header Settings in Celeris Web

> Configure sidebar and header settings in Celeris Web via the ProjectSetting object and Pinia store. Learn how to define layouts and manage reactive state for your admin panel.

- Repository: [Kirk Lin/celeris-web](https://github.com/kirklin/celeris-web)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Sidebar and header settings in Celeris Web are configured through the centralized `ProjectSetting` configuration object, which defines default layouts in [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts) and exposes reactive state management through Pinia store getters and dedicated Vue composables (`useHeaderSetting` and `useMenuSetting`).**

Customizing the admin dashboard layout in the kirklin/celeris-web repository relies on a type-safe configuration system that controls the visibility and behavior of the global header and sidebar navigation. These settings are initialized with sensible defaults in TypeScript, managed reactively through the application's Pinia store in [`apps/admin/src/store/modules/app.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/store/modules/app.ts), and consumed by Vue components to programmatically toggle UI elements or persist user preferences across sessions.

## Configuration Architecture and Type Definitions

Celeris Web centralizes UI layout preferences within the **ProjectSetting** interface, which aggregates both header and menu (sidebar) configurations into a single project-wide object.

### Default Project Settings

The default values for all layout configurations reside in [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts). This file exports `DEFAULT_PROJECT_SETTING`, which populates the Pinia store on initialization. Changing these defaults affects the initial state of every new session before any user overrides are applied.

### Type Definitions

The TypeScript interfaces defining the shape of these settings are located in [`packages/web/types/src/config.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/web/types/src/config.ts). This file declares `HeaderSetting` and `MenuSetting`, ensuring type safety across the monorepo. The `HeaderSetting` interface controls the top navigation bar's visibility and features, while `MenuSetting` manages the left-hand sidebar navigation state.

## Configuring Header Settings

Header configuration is governed by the `HeaderSetting` interface, which provides granular control over individual header elements. In [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts), the default `headerSetting` object initializes the following properties:

- **`shouldShow`**: Boolean flag to show or hide the entire top header bar (default: `true`)
- **`shouldShowFullScreen`**: Displays the full-screen toggle button (default: `true`)
- **`shouldShowSearch`**: Shows the global search input in the header (default: `true`)
- **`shouldShowNotice`**: Displays the notification bell icon (default: `true`)
- **`shouldShowSettingDrawer`**: Controls visibility of the settings drawer toggle button (default: `false`)

To modify header settings programmatically, import the `useHeaderSetting` composable from [`apps/admin/src/composables/setting/useHeaderSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/composables/setting/useHeaderSetting.ts):

```typescript
import { useHeaderSetting } from "~/composables/setting/useHeaderSetting";

const { 
  getShouldShowHeader, 
  setHeaderSetting,
  toggleShouldShowSettingDrawer 
} = useHeaderSetting();

// Hide the header entirely
setHeaderSetting({ shouldShow: false });

// Toggle the settings drawer button
toggleShouldShowSettingDrawer();

```

The `setHeaderSetting` method accepts a `Partial<HeaderSetting>` object, merging updates with existing state rather than replacing the entire configuration.

## Configuring Sidebar (Menu) Settings

Sidebar behavior is managed through the `MenuSetting` interface, which primarily controls the collapsed state of the left-hand navigation. The key property is **`collapsed`**, a boolean defaulting to `false` in `DEFAULT_PROJECT_SETTING`.

The `useMenuSetting` composable in [`apps/admin/src/composables/setting/useMenuSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/composables/setting/useMenuSetting.ts) provides the primary API for sidebar manipulation:

```typescript
import { useMenuSetting } from "~/composables/setting/useMenuSetting";

const { getCollapsed, setCollapsed, toggleCollapsed } = useMenuSetting();

// Programmatically collapse the sidebar
setCollapsed(true);

// Toggle current state
toggleCollapsed();

// React to state changes
watchEffect(() => {
  console.log('Sidebar collapsed:', getCollapsed.value);
});

```

The sidebar layout component at [`apps/admin/src/layouts/sidebar/index.vue`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/layouts/sidebar/index.vue) consumes these reactive getters to apply CSS transitions and layout adjustments when the collapsed state changes.

## State Management with Pinia

The [`apps/admin/src/store/modules/app.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/store/modules/app.ts) file defines the central Pinia store that holds the `ProjectSetting` state. The store exposes specific getters and actions for header and menu settings:

- **`getHeaderSetting`**: Returns the current `HeaderSetting` object
- **`getMenuSetting`**: Returns the current `MenuSetting` object
- **`setHeaderSetting(headerSetting: Partial<HeaderSetting>)`**: Merges partial updates into the header configuration
- **`setMenuSetting(menuSetting: Partial<MenuSetting>)`**: Merges partial updates into the menu configuration

Direct store access is available through `useAppStore()`, though the composables provide a more convenient abstraction for components.

## Persisting Settings Across Sessions

By default, Celeris Web persists `ProjectSetting` changes to **local storage** using the `PermissionCacheTypeConstants.LOCAL_STORAGE` cache type configured in `DEFAULT_PROJECT_SETTING`. When you invoke `setHeaderSetting` or `setMenuSetting`, the Pinia store automatically serializes the updated state to local storage. On application initialization, the store hydrates itself from this cached data, ensuring user preferences survive page reloads without requiring additional boilerplate code.

## Key Source Files Reference

| Purpose | File Path | Description |
|---------|-----------|-------------|
| Default Configuration | [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts) | Exports `DEFAULT_PROJECT_SETTING` with initial header and menu values |
| Type Definitions | [`packages/web/types/src/config.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/web/types/src/config.ts) | Contains `HeaderSetting` and `MenuSetting` TypeScript interfaces |
| Pinia Store | [`apps/admin/src/store/modules/app.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/store/modules/app.ts) | Central state management for project settings |
| Header Composable | [`apps/admin/src/composables/setting/useHeaderSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/composables/setting/useHeaderSetting.ts) | Vue composable exposing header getters and mutations |
| Menu Composable | [`apps/admin/src/composables/setting/useMenuSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/composables/setting/useMenuSetting.ts) | Vue composable for sidebar collapsed state management |
| Header Layout | [`apps/admin/src/layouts/header/index.vue`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/layouts/header/index.vue) | Component rendering the top navigation bar |
| Sidebar Layout | [`apps/admin/src/layouts/sidebar/index.vue`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/layouts/sidebar/index.vue) | Component rendering the left navigation menu |

## Summary

- **ProjectSetting** acts as the single source of truth for both header and sidebar configurations in Celeris Web.
- Default values are defined in [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts) and typed in [`packages/web/types/src/config.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/web/types/src/config.ts).
- The **Pinia store** ([`apps/admin/src/store/modules/app.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/store/modules/app.ts)) manages reactive state through dedicated getters and mutation actions.
- **Composables** (`useHeaderSetting` and `useMenuSetting`) provide the recommended developer API for reading and modifying layout state within Vue components.
- Changes persist automatically to local storage via the configured cache mechanism.

## Frequently Asked Questions

### Where are the default sidebar and header settings defined in Celeris Web?

Default settings are defined in [`apps/admin/src/setting/projectSetting.ts`](https://github.com/kirklin/celeris-web/blob/main/apps/admin/src/setting/projectSetting.ts) within the `DEFAULT_PROJECT_SETTING` object. The header defaults are nested under the `headerSetting` property, while sidebar defaults live under `menuSetting`. Type definitions for these objects are located in [`packages/web/types/src/config.ts`](https://github.com/kirklin/celeris-web/blob/main/packages/web/types/src/config.ts).

### How do I programmatically collapse the sidebar in Celeris Web?

Import the `useMenuSetting` composable from `~/composables/setting/useMenuSetting` and call either `setCollapsed(true)` to explicitly collapse it or `toggleCollapsed()` to switch between states. The composable returns reactive getters that automatically update the UI when the state changes.

### Can I hide specific elements like the search box or fullscreen button in the header?

Yes. Use the `useHeaderSetting` composable and call `setHeaderSetting()` with the specific boolean flags you want to modify, such as `{ shouldShowSearch: false }` or `{ shouldShowFullScreen: false }`. Each property controls a distinct UI element independently.

### Are sidebar and header settings persisted automatically between page reloads?

Yes. Celeris Web automatically persists `ProjectSetting` mutations to local storage when configured with `PermissionCacheTypeConstants.LOCAL_STORAGE`. The Pinia store hydrates from this cache on application startup, maintaining user preferences across sessions without requiring manual local storage handling.