NV Elements Catalog Starters Repo System Themes About Getting Started Changelog Metrics Support Accessibility Contributions Requests Migration Deprecations Integrations Installation MCP CLI Lint Angular Bundles Extensions Go Hugo Import Maps Lit NextJS Nuxt Preact React SolidJS Svelte TypeScript Vue Foundations Typography Iconography Themes Design Tokens Size & Space Objects Interactions Support Status Color Animation Fonts Layers Custom Layout Horizontal Vertical Grid Popovers i18n Visualization View Transitions Elements Accordion Alert Avatar Badge Breadcrumb Button Button Group Card Chat Message Checkbox Color Combobox Copy Button Datagrid Integrations Column Action Column Alignment Column Fixed Column width Container Card Display Settings Footer Heatmap Keynav Multi Select Pagination Panel Detail Panel Grid Performance Placeholder Row Action Row Groups Row Sort Scroll Height Single Select Stripe Date Datetime Dialog Divider Dot Drawer Dropdown Dropdown Group Dropzone File Forms Validation Actions Control Icon Icon Button Input Input Group Logo Menu Month Notification Page Page Header Page Loader Pagination Panel Progressive Filter Chip Progress Bar Progress Ring Password Preferences Input Pulse Radio Range Resize Handle Search Select Skeleton Sort Button Sparkline Star Rating Steps Switch Tabs Tag Textarea Time Toast Toggletip Toolbar Tooltip Tree Week Patterns Authentication Browse Dashboard Editor Empty States Heatmap Keyboard Shortcut Logging Media Onboarding Panel Responsive Search Subheader Trend Code Codeblock Monaco Input Diff Input Editor Diff Editor Problems Markdown Markdown CSS Utility Labs Responsive Layout Viewport Container Patterns Forms API Design Properties & Attributes Slots Registration CustomEvents Stateless Composition Styles Packaging Glossary Logs Internal Guidelines Agent Harness Documentation Examples TypeScript Testing Unit Testing Accessibility Testing Lighthouse Testing SSR Testing Visual Testing Troubleshooting Component Creation Internal Examples All Examples

API Design Guidelines

What this document is

This document outlines the API best practices and guidelines for creating highly reusable UI components/elements that work in any framework or library. The best practices defined here target low level leaf components and may not apply to all use cases of an application or plugin.

What this document is not

This document is not intended to define the best practices and API design of higher level UI components used at the micro-frontend/plugin/application level. While some of the recommendations and best practices outlined in this document are applicable, not all apply outside of the reusable UI element library use case.

Legend

Do: a best practice to follow Don't: a practice to avoid Tip: helpful details on rationale for a given guideline details on the risks of not following a guideline 🏁 Performance: detail about how a guideline impacts performance 🎓 Learn: resource to learn more about a guideline topic 🚧 WIP: details on any work in progress guidance

Terminology

  • Element: a Web Component defined within the public API of the library
  • Component: higher level UI web/framework components in plugins/apps
  • Pattern: combination of elements to create a UI rather than creating new extra elements
  • Pattern Library: packaged library of patterns/behaviors composed of low level elements
  • Plugin/Application: code that consumes or uses the elements
  • Consumers: developers/designers that use the UI elements within their products

Philosophy

Web standards over frameworks

  • Stateless over Stateful
  • Composable Patterns over Custom Features
  • Common Design Language for developers and designers
  • Internationalizable by default
  • Accessible by default
  • Automated conventions and best practices

Consistent element APIs provide consistent developer experience. The recommendations in this document provide a path of optimal compatibility with other framework integrations, including

  • routing/linking
  • native form controls / validation
  • key navigation
  • property/event binding/content projection
  • i18n/a11y
See an example of how many frameworks can use a Web Component based design system.