# Sections

Sections are the building blocks of pages — self-contained UI components that define their own content, design, and rendering logic. Merchants interact with sections through the Instant Site Editor, where they can customize content (text, images, buttons) and design (colors, fonts, backgrounds) based on settings you define.

### Section Types <a href="#section-types" id="section-types"></a>

Every section has a `type` that determines where it can be used:

| Type      | Purpose                                                                                                  |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `SECTION` | Standard page section — used within template pages                                                       |
| `HEADER`  | Site header — appears at the top of every page. Has [#mandatory-settings](#mandatory-settings "mention") |
| `FOOTER`  | Site footer — appears at the bottom of every page                                                        |

{% hint style="info" %}
Headers and footers are structurally identical to sections with a few additional constraints. See [Headers](/site-themes/develop-site-themes/headers.md) and [Footers](/site-themes/develop-site-themes/footers.md) for details.
{% endhint %}

### Folder Structure <a href="#folder-structure" id="folder-structure"></a>

Each section lives in its own directory under `sections/`:

```
sections/<section-name>/
├── client.ts            # Client-side hydration entry point
├── server.ts            # Server-side rendering entry point
├── Section.vue          # Vue component
├── type.ts              # TypeScript type definitions (Content, Design)
├── settings/
│   ├── content.ts       # Content editor definitions
│   ├── design.ts        # Design editor definitions
│   ├── layout.ts        # Layout configurations (optional)
│   └── translations.ts  # Translation strings (optional)
└── showcases/           # Showcase configurations (optional)
    ├── 1.ts
    ├── 2.ts
    └── translations.ts  # Showcase-specific translations (optional)
```

### Files Overview <a href="#files-overview" id="files-overview"></a>

#### Entry Points <a href="#entry-points" id="entry-points"></a>

* **`server.ts`** — Server-side rendering entry point. Uses `createVueServerApp` to render the section to HTML on the server. See [Server](/site-themes/develop-site-themes/sections/server.md)
* **`client.ts`** — Client-side hydration entry point. Uses `createVueClientApp` to hydrate the server-rendered HTML in the browser. See [Client](/site-themes/develop-site-themes/sections/client.md)

#### Component and Types <a href="#component-and-types" id="component-and-types"></a>

* **`Section.vue`** — The Vue 3 component that renders the section UI. Uses [UI Composables](/site-themes/develop-site-themes/sections/ui-composables.md) to access content and design data.
* **`type.ts`** — TypeScript type definitions using `InferContentType` and `InferDesignType` to derive types from your settings files.

#### Settings <a href="#settings" id="settings"></a>

Settings files define what merchants can customize in the Editor. They determine which editors appear (text inputs, image uploaders, color pickers, etc.) and their default values.

* **`content.ts`** — Defines content editors (text, images, buttons, etc.)
* **`design.ts`** — Defines design editors (colors, fonts, backgrounds, etc.)
* **`layout.ts`** — Defines layout variations for the section (optional)
* **`translations.ts`** — Multi-language text for editor labels and defaults (optional)

See [Settings](/site-themes/develop-site-themes/sections/settings.md) for full documentation.

#### Showcases <a href="#showcases" id="showcases"></a>

Showcases define pre-configured variations of a section with specific default content and design values. They appear as selectable presets when merchants add the section to a page.

See [Showcases](/site-themes/develop-site-themes/sections/showcases.md) for details.

### Mandatory Settings <a href="#mandatory-settings" id="mandatory-settings"></a>

Sections with type `HEADER` have mandatory settings that must be present:

**Content:** `menu` (type `NAVIGATION_MENU`) and `logo` (type `LOGO`)

**Design:** `logo` (type `LOGO`)

These are enforced at build time. Standard `SECTION` and `FOOTER` types have no mandatory settings.

### Linting <a href="#linting" id="linting"></a>

Crane provides `@lightspeed/eslint-config-crane` — a preconfigured ESLint setup for section development. The template scaffolds an `eslint.config.cjs` that consumes it as a one-liner:

```cjs
// eslint.config.cjs
module.exports = require('@lightspeed/eslint-config-crane');
```

#### What It Includes <a href="#what-it-includes" id="what-it-includes"></a>

* **Vue 3** — `eslint-plugin-vue` with recommended rules
* **TypeScript** — `@vue/eslint-config-typescript` recommended rules
* **Scoped CSS** — `eslint-plugin-vue-scoped-css` recommended rules
* **Accessibility** — `eslint-plugin-vuejs-accessibility`

#### Notable Rules <a href="#notable-rules" id="notable-rules"></a>

| Rule                      | Setting                       | Description                                        |
| ------------------------- | ----------------------------- | -------------------------------------------------- |
| `vue/component-api-style` | `script-setup`, `composition` | Only Composition API with `<script setup>` allowed |
| `max-len`                 | 160                           | Maximum line length for `.ts` and `.vue` files     |
| `no-console`              | warn                          | Console statements produce warnings                |
| `no-debugger`             | warn                          | Debugger statements produce warnings               |

#### Running the Linter <a href="#running-the-linter" id="running-the-linter"></a>

The template does not include a lint script by default. Run ESLint directly:

```bash
npx eslint "./**/*.{js,ts}"
```

Or add a script to your `package.json`:

```json
{
  "scripts": {
    "lint": "eslint \"./**/*.{js,ts}\""
  }
}
```

### Advanced Composables <a href="#advanced-composables" id="advanced-composables"></a>

These composables are exported from `@lightspeed/crane-api` for advanced use cases. Most sections won't need them.

#### `useVueBaseProps` <a href="#usevuebaseprops" id="usevuebaseprops"></a>

Low-level composable providing reactive access to the full section context:

* `context` — store and environment information
* `content` — raw content data
* `design` — raw design data
* `defaults` — default values
* `site` — site configuration (languages, currency, etc.)
* `category` — current category data (on category pages)
* `storeData` — store metadata
* `globalDesign` — global design settings (colors, fonts, text sizes)
* `tileId` — the section's tile identifier

Use this when the typed content/design composables are not sufficient — for example, when accessing global design tokens directly or reading site-level configuration.

#### `useInstantsiteJsApi` <a href="#useinstantsitejsapi" id="useinstantsitejsapi"></a>

Returns `window.instantsite` — the platform's JavaScript API for interacting with the storefront runtime (e.g., triggering cart updates, navigation events).

```typescript
import { useInstantsiteJsApi } from '@lightspeed/crane-api';

const api = useInstantsiteJsApi();
```

{% hint style="info" %}
**Client-Only**

This is a client-only API. Guard usage with `typeof window !== 'undefined'` or call it inside `onMounted`. See [SSR vs Client-Only Rendering](https://ecwid.github.io/crane/guide/sections/ui-composables#ssr-vs-client-only-rendering).
{% endhint %}

### Learn more <a href="#next-steps" id="next-steps"></a>

* [Client](/site-themes/develop-site-themes/sections/client.md) — Client-side hydration
* [Server](/site-themes/develop-site-themes/sections/server.md) — Server-side rendering
* [Settings](/site-themes/develop-site-themes/sections/settings.md) — Define content and design editors
* [Showcases](/site-themes/develop-site-themes/sections/showcases.md) — Pre-configured section variations
* [UI Composables](/site-themes/develop-site-themes/sections/ui-composables.md) — Access content and design data in Vue components


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/sections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.