---
title: "Sections and blocks"
description: "Author typed storefront components with settings, regions, presets, and hydration policy."
canonical_url: "https://nyxel.dev/docs/sections"
markdown_url: "https://nyxel.dev/docs/sections.md"
---

# Sections and blocks
URL: /docs/sections
LLM index: /llms.txt
Description: Author typed storefront components with settings, regions, presets, and hydration policy.

# Sections and blocks

A Nyxel component is an ordinary Svelte, Astro, or React component with one static TypeScript contract. The contract tells the registry and editor what the component is, which values can be edited, where children may be placed, and whether the browser should hydrate it.

![Nyxel Inspector showing typed settings for the storefront header.](/site-media/editor-schema-controls.png)

## A minimal Svelte section

```svelte
<script module lang="ts">
	import { colorScheme, section, text } from '@nyxel/component'

	export const nyxel = section({
		type: 'hero',
		name: 'Hero',
		category: 'Content',
		settings: {
			heading: text({ label: 'Heading', default: 'New arrivals' }),
			color_scheme: colorScheme({ label: 'Color scheme', default: 'scheme-1' })
		},
		hydration: 'server'
	})
</script>

<script lang="ts">
	type Props = {
		settings: import('@nyxel/component').InferSettings<typeof nyxel>
	}

	let { settings }: Props = $props()
</script>

<section data-color-scheme={settings.color_scheme}>
	<h1>{settings.heading}</h1>
</section>
```

The setting keys connect the entire workflow. `heading` produces a typed `settings.heading` value, an editor control, a default, validation rules, and a persisted override when the author changes it.

## Settings

Builders describe both data and control behavior. Text, rich text, numbers, ranges, checkboxes, selects, URLs, colors, media, icons, resource pickers, list pickers, and dynamic-source-compatible values share one normalized representation.

Presentation entries such as `header()` and `paragraph()` organize the Inspector but do not become persisted settings. Numeric controls normalize to numbers at the control boundary. List resource pickers return arrays. Defaults live in the contract and templates store sparse overrides.

Settings should describe meaningful component choices. Mechanical styling belongs in reusable theme tokens or the component’s own CSS; an unrestricted “custom CSS” field is not a substitute for a clear contract.

## Named regions

Regions define where child nodes may be inserted:

```ts
import { block, region, text } from '@nyxel/component'

export const nyxel = block({
	type: 'card',
	name: 'Card',
	settings: {
		title: text({ label: 'Title', default: '' })
	},
	regions: {
		media: region({ accepts: ['image', 'video'], maxItems: 1 }),
		content: region({ accepts: ['text', 'button'] })
	}
})
```

The runtime preserves each region’s order. The editor uses the same constraints for add menus and drag targets, and every renderer receives the same semantic child groups in its native syntax.

## Presets and route restrictions

Presets provide useful starting trees rather than empty components. A preset can include settings, nested blocks, regions, and dynamic source bindings. Keep starter data generic: bind route resources such as the current product instead of committing store-specific Shopify IDs.

`enabledOn` and `disabledOn` restrict where a component can be added. Use them for real structural rules, such as a cart surface that only belongs on the cart template, rather than as a substitute for resilient component design.

## Hydration

`server` is the default policy. Use `load`, `idle`, `visible`, or `media` only when the component needs browser behavior. Astro owns mixed-framework recursion, so a Svelte parent can receive a React or Astro child without either component becoming responsible for framework dispatch.

## Extraction and diagnostics

The scanner parses `.svelte` module scripts, `.astro` frontmatter, and `.tsx` named exports. It evaluates only literal objects, arrays, recognized builder calls, and local static constants; it never imports the component during registry scanning.

Computed property names, environment reads, arbitrary function execution, and unknown spreads are rejected with stable `NXY*` diagnostics. Run `pnpm nyxel inspect component <path>` to see the extracted contract and normalized manifest, then `pnpm nyxel check` before handing off a component change.

![Nyxel Components library showing the storefront header component and its settings.](/site-media/editor-components.png)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).