A container that keeps content at a readable width with even spacing. It also sets the background and the theme scope.
Live example
These are real Section blocks rendering on this page right now. Tab to them and try them in both color schemes.
Constrained-width content wrapper without a background fill.
Section with backgroundColor “layer-01” — Carbon’s subtle surface tone.
Section with backgroundColor “layer-02”.
Narrow section — for prose-width content.
Wide section.
Dark-scope section. Carbon tokens resolve to the dark palette inside this island regardless of the page’s active theme.
Dark-scope section via the “dark” alias — resolves to the active style variation’s paired dark scope (falls back to g100 when the theme isn’t active).
Light-scope section via the “light” alias — resolves to the active style variation’s paired light scope (falls back to white when the theme isn’t active).
Section with extra vertical padding.
Dark mode you don’t have to build
Every block supports dark mode. Use the light/dark toggle in the header and the live example above switches with it.
Parameters
Everything the Section block accepts. Setting is the label you see in the block’s settings panel. Parameter is what the same value is called in code. Accepts is what you can put in it.
| Setting | Parameter | Type | Default | Accepts | What it does |
|---|---|---|---|---|---|
| Vertical padding | paddingBlock | string | “07” | Carbon spacing steps 01 to 13 | The vertical padding, as a Carbon spacing step. |
| Horizontal padding | paddingInline | string | “06” | Carbon spacing steps 01 to 13 | The horizontal padding, as a Carbon spacing step. |
| No gap below | noGapBelow | boolean | false | true or false | Removes the space below this section so it sits flush against whatever comes next. Overrides the Spacing setting. |
| Max width | maxWidth | string | “content” | none, narrow, content, wide, custom | How wide the content column is. |
| Custom max width (e.g., 720px) | customMaxWidth | string | empty | A CSS width, for example 60rem | Your own width when maxWidth is custom. |
| Background color | backgroundColor | string | empty | empty, background, layer-01, layer-accent-01 | A Carbon background token, so it keeps its contrast in light and dark mode. |
| Theme scope | themeScope | string | “inherit” | inherit, light, dark, g10, g100 | Renders this section in a different Carbon theme than the page, for example a dark band on a light page. |
| HTML tag | tagName | string | “section” | section, div, article, aside | The HTML element the section renders as. |
| Accessible name (aria-label) | ariaLabel | string | empty | Any text | Names the section as a landmark for screen readers. |
Accessibility parameters, on this and every AWT block
Every AWT block has an Accessibility panel in its settings. Each control in it becomes a real HTML attribute on the block’s outer element:
| Setting | Parameter | What it does |
|---|---|---|
| Accessible name (aria-label) | ariaLabel | Becomes aria-label on the block’s outer element. Replaces the accessible name screen readers announce. Set it only when the visible label is not enough. |
| Described by (aria-describedby) | ariaDescribedby | Becomes aria-describedby. Point it at the ID of another element on the page whose text adds a longer description. |
| Labelled by (aria-labelledby) | ariaLabelledby | Becomes aria-labelledby. Point it at the ID of another element whose text should become this block’s accessible name. |
| Role | awtRole | Becomes the role attribute. Overrides the element’s ARIA role. The list offers only roles that suit the element. |
| Language (lang) | awtLang | Becomes the lang attribute. Set it when this block’s content is in a different language from the page, as a BCP-47 code like “fr”. |