Troubleshooting

Find the symptom you’re seeing. If none of these fixes it, ask for help with the details listed there.

Installing the packages

401 Unauthorized. npm reached GitHub Packages without a valid token. Check that .npmrc has the _authToken line from Installation, that NBHD_TOKEN is set if you reference it, and that the token hasn’t expired. Build and deploy environments need the token too.

403 Forbidden. The token works, but it doesn’t have access to the packages. Request package access for the project.

404 Not Found for @fbin-web/…. npm looked on the public registry instead of GitHub Packages. Add the @fbin-web:registry=https://npm.pkg.github.com line to .npmrc, in the project root.

Components look wrong

A component shows as plain text, or not at all. It isn’t registered. Import @fbin-web/neighborhood-core, or the component, in code that runs in the browser, or load build/library/neighborhood.js with a script tag. Only content in slots shows before then; see Before components load.

A component renders, but as an unstyled button or box. The stylesheet didn’t load. Each page needs one brand stylesheet or the unbranded tokens. Check the browser’s network panel for the CSS file.

Failed to resolve module specifier "lit" in the console. A file from dist/ was loaded with a script tag. Those files expect a bundler. Use build/library/neighborhood.js instead.

Colors or spacing from two brands. Two brand stylesheets are loaded, and the later one overrides parts of the first. Load one per page.

The wrong font. The brand’s font files didn’t load:

• Without a bundler, copy the brand’s whole folder, including fonts/, not just the CSS file.
• If your site loads the fonts itself, the family names and weights must match the brand’s. See Installation.
• On Shopify, the fonts need their own stylesheet; see Platform setup.

Styling

A custom property has no effect. It has to be set inside a selector, on the component or a parent, and the name must match exactly, including its camelCase parts: --nbhd-card-borderRadius, not --nbhd-card-border-radius. Each component page lists its names under CSS Properties. See Styling.

Slotted text or links look different from Storybook. Slotted content is part of your page, so your site’s CSS applies to it. Look for page-wide rules on p, a, ul or headings, such as those from a CSS reset, Bootstrap or Tailwind’s base styles, and scope them away from Neighborhood sections. The precompiled Neighborhood CSS files include Tailwind’s reset.

A style broke after an update. Custom properties with an underscore, such as --nbhd-_card-overlay-display, and the elements inside a component aren’t part of the public API and can change in any release. Use the component’s options, custom properties or parts instead.

Events and data

An event listener never runs. Neighborhood events start with nbhd-, such as nbhd-page-changed. In React, use the onNbhd* prop, such as onNbhdPageChanged. See React.

A list or object doesn’t show. Lists and objects, such as a Select’s items, have to be set as properties, in JavaScript or with your framework’s property binding. As an HTML attribute, they’re ignored. See Platform setup.

A React prop wiped out a default. Passing undefined replaces the component’s default. Leave the prop out instead. See React.

A Dialog won’t open a second time. Your open state didn’t follow the Dialog when it closed itself. Set it back to false from nbhd-dialog-close. See React.

Frameworks

Vue: Failed to resolve component: nbhd-…. Vue doesn’t know the tag is a custom element. Add the isCustomElement setting from Platform setup.

Angular: 'nbhd-…' is not a known element. Add CUSTOM_ELEMENTS_SCHEMA to the component’s schemas.

Forms

A field isn’t in the submitted data. Give it a name. Fields without one aren’t submitted, as with native fields.

The form submits even though a field shows an error. invalid only shows the error state. To block submission, use required and the other validation attributes, or call setCustomValidity(message). See Use components in forms.

Values are sent twice. The fields submit with the form on their own, so hidden inputs that copy their values send them again. Remove the hidden inputs.

After upgrading

Colors are missing from your own CSS. Older color tokens were removed in v5, such as --nbhd-content-* and --nbhd-background-*. Replace them with the --nbhd-color-* tokens, such as --nbhd-color-text-primary. The changelog lists each change.

Your site loads core.css from the brands package. It was removed in v5. Use the brand’s all.css, or its token file if your site loads the fonts itself.

Check which version you have. Run npm ls @fbin-web/neighborhood-core, then use the docs for that version from the Versions page.

Warnings in the console

In development, components warn about some accessibility problems, such as an image with no alt or an icon-only button with no aria-label. Fix them as described in Accessibility.