README
ni | nimble | components
Nimble Components
NI-styled web components for web applications.
Getting Started
Framework Support
If you are using one of the following frameworks see associated wrapper documentation:
- Angular: See the nimble-angular documentation.
- Blazor WebAssembly or Blazor Server: See the nimble-blazor documentation.
nimble-components
in a Webpack Application
Using If you have an existing application that incorporates a module bundler like Webpack but doesn't include one of the above frameworks, you can use @ni/nimble-components
directly. Exact instructions will depend on your application, but here are some common steps:
- Install the package from the public NPM registry by running
npm install @ni/nimble-components
. - Import the component you want to use from the file you want to use it in. For example:
import '@ni/nimble-components/dist/esm/icons/succeeded';
- Add the HTML for the component to your page. You can see sample code for each component in the Nimble Storybook by going to the Docs tab for the component and clicking Show code. For example:
<nimble-succeeded-icon></nimble-succeeded-icon>
. - Nimble components are standard web components (custom elements) so you can configure them via normal DOM APIs like attributes, properties, events, and methods. The Storybook documentation for each component describes its custom API.
Theming
This package contains a theming system which enables changing the appearance of controls based on user preferences or application designs.
The theming system is built on a set of design tokens that define different properties such as fonts, colors, etc. The Nimble components are configured to use these theme-aware design tokens. An application should use the same theme-aware design tokens for parts outside of the components.
The theming system is composed of:
- Theme-aware design tokens that are used in your stylesheets.
- A
<nimble-theme-provider>
component that is added around your page contents and is configured for a theme.
Using the Theming System
Include the
<nimble-theme-provider>
element on your page and set itstheme
attribute. The theme provider has no appearance of its own but defines tokens that are used by descendant components. It will typically be at the root of the application:<body> <nimble-theme-provider theme="light"> <!-- everything else --> </nimble-theme-provider> </body>
Include one import in your styles for the Nimble fonts. Nimble recommends using SCSS for capabilities such as build-time property checking.
@import '~@ni/nimble-components/dist/fonts';
As needed, add Nimble components as descendants of the theme provider and they will inherit the theme.
As needed, import the theme-aware design tokens in each SCSS file that will leverage the tokens for other parts of your application (for colors, fonts, etc).
@import '~@ni/nimble-components/dist/tokens'; .my-element { font-family: $ni-nimble-font-family; }
Customizing
The goal of the Nimble design system is to provide a consistent style for applications. If you find that Nimble does not expose colors, fonts, sizes, etc. that you need in an application get in touch with the Nimble squad.
Accessibility
For accessibility information related to nimble components, see ACCESSIBILITY.md.
Contributing
Follow the instructions in CONTRIBUTING.md to modify this library.