Styling

Neighborhood components keep their styles inside a shadow DOM (opens in new tab) . Your page’s CSS can’t reach the elements inside a component, so site styles can’t break it by accident. To customize a component, you use the styling options it provides.

Start with the lightest change

Try these in order, and stop at the first one that works. Options further down the list are more likely to need changes when Neighborhood updates.

1. Use the component’s own options. Attributes such as variant and surface cover most needs. Each component page lists them under Properties.
2. Set a CSS custom property. Change one value, such as a radius or a color, with a --nbhd-* property.
3. Style a CSS part. Reach one named element inside the component with ::part().
4. Ask for a change. If none of these gets you there, request a change. A new option in the component works for every site, not just yours.

CSS custom properties

Components read their styles from CSS custom properties (opens in new tab) , also called CSS variables. Set one and the component uses your value instead of its default.

Component properties start with --nbhd-, then the component name, then the CSS property they control: --nbhd-card-borderRadius. Each part of the name is camelCase, and the parts are separated by hyphens. Working with tokens explains the full pattern.

Custom properties only take effect inside a selector. Set them on the component’s tag so the change applies only where you mean it to:

/* Won't work: not inside a selector */
--nbhd-card-borderRadius: var(--nbhd-border-radius-md);

/* Works, but changes every card on the site */
:root {
  --nbhd-card-borderRadius: var(--nbhd-border-radius-md);
}

/* Best: scoped to the cards you mean */
.product-grid nbhd-card {
  --nbhd-card-borderRadius: var(--nbhd-border-radius-md);
}

Set custom properties to tokens, not fixed values. A token follows the brand theme, so the same CSS works on every brand:

/* Avoid: a fixed color ignores the brand theme */
nbhd-card {
  --nbhd-card-borderColor: #1b5e20;
}

/* Use: a token follows the brand theme */
nbhd-card {
  --nbhd-card-borderColor: var(--nbhd-color-accent-primary);
}

Each component page lists the properties it reads under CSS Properties.

A property with an underscore after --nbhd-, such as --nbhd-_card-overlay-display, is internal to the component. Don’t set these; they can change in any release.

CSS parts

Some components expose named elements as CSS parts (opens in new tab) . Write the component’s tag, then ::part() with the part name inside, without quotes:

nbhd-text::part(base) {
  text-wrap: balance;
}

Keep part rules small, and use tokens for any values. A part gives you access to one element, but the component may change how that element is styled in a future release. Each component page lists its parts under CSS Parts.

Logical properties

Neighborhood uses CSS logical properties (opens in new tab) throughout. Instead of top, bottom, left and right, logical properties use block (the direction text flows down the page) and inline (the direction text runs along a line). Layouts then adapt to right-to-left languages without extra CSS.

Use logical properties in your own CSS too, so it lines up with the components:

.promo {
  max-inline-size: 60ch;
  margin-block-end: var(--nbhd-space-6);
  padding-inline: var(--nbhd-space-4);
}

Component custom properties use the same names, such as --nbhd-card-paddingBlock and --nbhd-card-maxInlineSize.