InstUI is Instructure's open-source React component library and design system, providing accessible, themeable UI components for Canvas LMS and other Instructure products.

Installation

npm install @instructure/ui

Import Pattern

// Umbrella package (recommended for most consumers)
import { Button, TextInput, Modal } from '@instructure/ui'

Setup

Wrap your app in a theme provider:

import { canvas } from '@instructure/ui-themes'
import { InstUISettingsProvider } from '@instructure/ui'

function App() {
  return (
    <InstUISettingsProvider theme={canvas}>
      {/* your app */}
    </InstUISettingsProvider>
  )
}

See usage.md for full setup details and theming-components.md for customization.

Instructure UI (InstUI) - React Component Library

version 11.6.0
Instructure UI (InstUI) is a comprehensive React component library.

Documentation

User Guides

Getting Started

Accessibility: Instructure UI targets WCAG 2.1 AA/AAA standards with proper color contrast, keyboard navigation, screen reader support, and ARIA compliance. Components are perceivable, operable, understandable, and robust.
Theming components: InstUI has two themes: canvas (default) and canvas-high-contrast. Colors are layered: primitives (base), contrasts (theme-specific), and UI (curated tokens). Use InstUISettingsProvider to set themes. Overrides allow customization but must maintain accessibility.
Usage: Quick start: Create a React app, add @instructure/ui, wrap with InstUISettingsProvider, and use components. Integrate with existing projects by adding the dependency and provider. Read about theme overrides and accessibility for best practices.

Guides

Accessing the dom: Guidance for properly accessing DOM elements in React components using refs instead of findDOMNode to avoid warnings. Examples show good and bad patterns for component ref handling.
Color system: Color system divided into primitive (hex values) and semantic (contextual) colors. Includes data visualization palette with primary and secondary hues for charts and graphs on white backgrounds.
Focus management: Comprehensive focus management system for dialogs, modals, and popovers. Uses Dialog component with FocusRegion and FocusRegionManager to trap focus, handle escape keys, and manage screen reader accessibility.
Form errors: InstUI form components use a messages prop for error/hint/success messages. Supports both error (legacy) and newError (accessible) types. Required fields now show an asterisk automatically. Examples provided for various form components like TextInput, Checkbox, and DateTimeInput.
Layout spacing: InstUI provides semantic spacing tokens (e.g., buttons, tags) for consistent layouts. Apply spacing via margin prop, container gap, or importing from theme. Legacy tokens are available for compatibility but not recommended for new layouts.
Module federation: InstUI supports module federation with specific version requirements. For v10.14+, use local themes (canvasThemeLocal). For older hosts, guest apps must use v10.14+ and local themes. Global theme overrides don't apply to local themes.
Server side rendering: SSR with Next.js requires wrapping the app with InstUISettingsProvider for deterministic ID generation. Avoid @instructure/ui meta-package; install only needed packages. CodeEditor isn't SSR-compatible and must be dynamically imported.
Typography system: Use <Text> and <Heading> components with semantic variants for consistent typography. Variants define font style, weight, size, and line height. Legacy tokens (e.g., fontSizeXSmall) are deprecated and should not be used in new designs.
Using theme overrides: Customize components via theme overrides while ensuring WCAG compliance. Use nested InstUISettingsProvider for subtree themes, override global or component themes, and leverage branding variables for user customization. Deprecated global theming causes issues with multiple InstUI versions.

Patterns

Content alignment: Guidelines for main content area alignment with maximum width (948px) for readability, minimum width (320px) for accessibility, and responsive padding (24px/12px). Ensures proper centering, avoids two-dimensional scrolling, and allows exceptions for complex data displays.
Destroy action: A modal used for irreversible actions like deletion. Includes guidelines for usage: use clear language, avoid vague confirmations, and use a danger button for the destructive action.
Search: Provides search input patterns including auto-activated, activated, and autocomplete search. Includes guidelines, accessibility support, and clear state management examples.
Using icons: Guidelines for using icons with proper accessibility roles, size variants, and color options. Line icons for light backgrounds, solid for dark backgrounds. Icons scale with parent font-size by default.

Components

InstUISettingsProvider: A global configuration component for applying themes and text direction settings across an application. It wraps Emotion's ThemeProvider and supports nested providers for theme inheritance and overrides. Also manages text direction (LTR/RTL) via context for descendant components.
Alert: Notifies users with contextual variants (success, info, error, warning). Supports dismissible dialogs, automatic timeout dismissal, live regions for screen readers, and inline usage without shadows. Includes accessibility guidelines for proper implementation.
Avatar: Displays user avatars with fallback to initials or icons. Supports circle/rectangle shapes, multiple sizes, colors, and inverse styling. Includes special AI avatar variant and accessibility considerations with aria-hidden attribute.
Badge: Displays numeric counts or notifications with accessibility features. Supports count limits, various placements, standalone usage, and color variants. Requires formatOutput prop for screen reader context beyond simple numbers.
Billboard: Used for empty states, 404 pages, and redirects. Supports various sizes, hero icons, and interactive behaviors (button or link). Can be disabled and includes structured messaging with headings and calls to action.
Breadcrumb: Shows navigation path location with automatic text truncation. Best for tablet+ screens; use Link for mobile. Supports multiple sizes, icons, and accessibility with aria-current attribute for current page indication.
Button: Triggers actions or changes with multiple color schemes, sizes, and display options. Supports icons, text wrapping control, and backgroundless variants. Includes specific AI button styles with gradients and icons.
CloseButton: Specialized button for closing modals, dialogs, or containers. Supports absolute positioning with placement options (start/end/static) and offset control. Built with accessibility in mind using IconButton with X icon and screen reader labels.
CondensedButton: Button variant without padding for tight spaces or alignment with other content. Ideal for table cells or areas where standard button padding would disrupt layout. Maintains button functionality while minimizing visual footprint.
IconButton: A button component designed specifically for icon-only actions. Requires screen reader labels for accessibility, supports various shapes (rectangle/circle), and can remove background/border for minimalist designs. Works well with Tooltip for additional context.
ToggleButton: Controlled button for toggling between two states (on/off), featuring icon support, tooltips, inverse variants for dark backgrounds, and accessibility labels. Perfect for status toggles like lock/unlock.
Byline: Combines visual elements (avatars, icons) with descriptive captions. Supports titles, various sizes, content alignment options, and margin control. Useful for author attribution or content metadata displays.
Calendar: Visual date selection component with configurable month navigation, disabled dates, selection handling, and optional year picker. Supports custom date libraries and accessibility features with proper weekday labels and screen reader support.
Checkbox: Custom styled checkbox component supporting standard, toggle, and indeterminate states. Includes size variants, accessibility features with aria-labelledby, and proper grouping for parent-child relationships. Guidelines recommend vertical stacking for multiple options.
CheckboxGroup: Groups multiple Checkbox components with shared name and value management. Supports vertical or horizontal layouts, toggle variants, and group-level disabled/readonly states. Handles validation messages and maintains consistent state across all checkboxes.
ColorContrast: WCAG 2.1 compliance tool that calculates and displays contrast ratios between two colors. Validates against normal text (4.5:1), large text (3:1), and graphics (3:1) standards. Provides pass/fail indicators and supports AA/AAA validation levels.
ColorIndicator: Displays color swatches with checkerboard background for transparency visualization. Supports circle and rectangle shapes, various color formats (hex, RGB, HSL, HWB), and can be used within buttons for color selection interfaces.
ColorMixer: Interactive color selection component with RGBA input fields, color sliders, and visual palette. Supports alpha transparency, keyboard navigation for accessibility, and can be disabled. Provides real-time color feedback and value changes.
ColorPicker: Versatile color selection component with hex input validation and optional popover color mixer. Supports controlled/uncontrolled operation, contrast checking, alpha transparency, and custom popover content. Includes comprehensive error messaging and accessibility features.
ColorPreset: Color selection from predefined palettes with support for adding/removing colors. Includes visual color indicators, screen reader labels, and optional color mixer integration for custom color creation. Handles color management and selection callbacks.
DateInput: A date input component with a calendar picker (uses Moment.js). Supports disabled dates, validation, and formatted display. Note: Being deprecated in favor of DateInput2 for better UX and accessibility.
DateInput2: An improved date input with easier configuration, better accessibility, and a year picker. Supports custom date parsing, timezone handling, validation, and disabled dates. Recommended over the original DateInput.
DateTimeInput: Combines DateInput and TimeSelect for entering date-time values. Supports localization, validation, disabled dates, and layout options (stacked or columns). Includes reset functionality and context-aware formatting.
DrawerLayout: A responsive layout component with a collapsible tray and content area. Tray can be placed at start or end and switches to overlay on small screens. Supports nested layouts and accessibility features.
Drilldown: A hierarchical navigation component for tree structures. Supports pages, groups, selectable options, and in-place editing. Replaces flyout menus and TreeBrowser for better responsiveness and accessibility.
Editable: Enables in-place editing of content. Manages state and transitions between view and edit modes. Provides render props for custom UI implementation. Used by InPlaceEdit.
InPlaceEdit: Enables inline editing of content with smooth transitions between view and edit modes. Provides controlled component pattern for mode management, custom renderers for viewer/editor components, and support for various layouts and read-only states.
FileDrop: A drag-and-drop file upload component with browse functionality. Supports file type validation via MIME types/extensions, multiple file uploads, and visual feedback for accepted/rejected files. Includes accessibility features and customizable rendering for labels and error messages.
Flex: A flexbox-based layout component for creating responsive multi-column designs. Supports directional layouts, gap control, item sizing (grow/shrink), alignment, and overflow handling. Includes visual debugging tools and common layout patterns like header-button combinations.
FormField: A foundational component for building form inputs with consistent styling and layout. Supports stacked and inline layouts, validation messages, and accessibility features. Typically used internally by other form components rather than directly.
FormFieldGroup: Organizes multiple form fields into cohesive groups with consistent spacing and alignment. Supports various layouts (inline, columns, stacked) and provides validation messaging at the group level. Includes accessibility guidance against placeholder text.
Grid: A 12-column grid system for creating responsive layouts. Features breakpoint-based stacking, customizable column widths, spacing control, and alignment options. Supports visual debugging and common patterns like responsive header layouts.
Heading: A typographic component for creating accessible headings with consistent styling. Supports semantic heading levels, color variants, borders, icons, and AI-specific styles. Includes important accessibility guidelines for proper heading hierarchy.
Img: An accessible image component with advanced features like color overlays, constraining options (cover/contain), and visual filters (grayscale/blur). Supports proper alt text implementation and follows accessibility guidelines for contextual vs. decorative images.
Link: An inline link component for navigation within text content. Supports variants (inline, inline-small, standalone, standalone-small), icons, margin, and underline control. Includes accessibility guidelines for proper usage and contrast.
InlineList: Displays list items horizontally with customizable delimiters, spacing, and sizing options. Supports various separator styles (pipe, slash, arrow) and controlled item spacing without affecting list boundaries.
List: A component for rendering ordered, unordered, or unstyled lists. Supports delimiters, spacing, sizing, and custom margins. Only accepts List.Item children and includes options for item spacing and visual customization.
Menu: A Popover-based component for action lists, often triggered by a button. Supports single/multiple selection, groups, separators, and nested menus. Not for navigation or complex content—only Menu.Items are allowed.
Metric: Displays a value and label with configurable text alignment (start, center, end). Used for showing key metrics like grades, counts, or percentages in a clean, aligned format.
MetricGroup: A container for displaying multiple Metric components in rows. Groups related metrics together for consolidated data presentation, such as grade-related statistics.
Modal: A centered dialog that overlays app content with a mask. Supports headers, bodies, footers, form integration, media display, and constrained positioning. Includes variants (default, inverse) and accessibility features.
AppNav: Navigation component for LTI apps that adapts to screen widths by truncating items. Provides update callbacks for visible item count and customizable truncation labels. Supports before/after items and responsive hamburger menu patterns.
NumberInput: A controlled input for numeric values with increment/decrement arrows. Supports validation, error messages, sizing, and accessibility. Must be used with event handlers; does not support uncontrolled usage.
Overlay: A closable/dismissible component that transitions content in and out via a Portal. Supports focus management, accessibility features, and can be used with Mask components. Includes guidelines for ensuring content behind the overlay is hidden from screen readers and dismissible with ESC key.
Pages: A component for rendering paginated content across multiple pages. Supports navigation between pages, back buttons, and focus management. Each page should contain at least one focusable element. Useful for multi-step workflows or detailed views like user profiles.
Pagination: Component for navigating through multi-page content. Offers compact, full, and input variants with configurable page indicators. Supports large page numbers, custom labels, and accessibility features. Includes both new simplified API and legacy support for complex pagination needs.
Pill: Displays short, contextual information with color-coded status indicators. Supports icons, status labels, and various color schemes. Text truncates with ellipsis if overflow occurs. Not intended for dismissible content or counts - use Tag or Badge components instead.
Popover: Shows/hides content connected to a trigger element via click, hover, or focus. Supports arrows, various placements, colors, and shadows. Can function as a dialog with focus trapping. Includes controlled and uncontrolled variants with extensive customization options.
ProgressBar: Styled HTML progress element with accessibility support. Offers multiple sizes, colors, and meter colors. Supports value formatting, animation, and screen reader customization. Meter color can be function-based for dynamic color changes.
ProgressCircle: Circular progress indicator with accessibility features. Supports sizes, colors, animations on mount, and custom value rendering. Meter color can be function-based. Useful for showing completion percentages in a compact visual format.
RadioInput: Custom styled radio button component. Typically used within RadioInputGroup for proper grouping and behavior. Supports different sizes and should always be used in groups rather than individually.
RadioInputGroup: Manages groups of radio buttons with shared name attribute. Supports various layouts (default, inline, columns), toggle variant, disabled states, and accessibility. Handles selection state and change events for the entire group.
RangeInput: An HTML5 range input/slider component with customizable size and thumb variants. Supports React class and functional component implementations with interactive examples for real-time updates.
Rating: Displays 3- or 5-star ratings based on valueNow and valueMax props. Supports rounding decimals, customizable sizes, animations, and accessibility-compliant text formatting for screen readers.
Responsive: Renders components differently based on element or viewport size. Supports breakpoint-based props and conditional rendering. Use sparingly to avoid performance issues.
Select: Accessible combobox component for single or multiple selections. Supports autocomplete, grouping, async loading, icons, and screen reader announcements. Fully controllable with extensive state management examples.
SideNavBar: Experimental top-level navigation component with toggleable minimized/expanded states. Supports icons, Avatars, badges, and theming. API may change significantly.
SimpleSelect: Simplified Select component mimicking native <select> behavior. Supports uncontrolled/controlled usage, option groups, and icons. Less configurable than Select but easier to implement.
SourceCodeEditor: Wrapper around CodeMirror with syntax highlighting, line numbers, folding, indentation, search, and RTL support. Recommended upgrade from deprecated CodeEditor component.
Spinner: Loading indicator with four sizes, inverse variant for dark backgrounds, configurable delay, and screen reader support via renderTitle prop.
Table: A versatile table component supporting multiple layouts (auto, fixed, stacked), column customization, sorting, selection, pagination, and responsive behavior. Includes accessibility features and supports custom components for advanced use cases.
Tabs: Accessible tabbed navigation component with support for secondary variants, overflow handling, size control, dynamic content, and tab persistence. Supports disabled tabs and controlled/uncontrolled usage patterns.
Tag: Compact component for representing categories or groups, featuring dismissible functionality, multiple sizes, inline variants, and accessibility support. Ideal for form elements and filtering interfaces.
Text: Comprehensive text styling component with semantic variants, color options, font properties, line heights, text transformation, and wrapping controls. Replaces deprecated legacy values with semantic alternatives.
TextArea: Resizable textarea input with height constraints, validation messages, disabled states, and inline display options. Supports controlled/uncontrolled usage and includes accessibility guidelines.
TextInput: Custom styled input supporting various types, prepend/append content, inline display, and controlled/uncontrolled behavior. Features validation, disabled/readonly states, and flexible content wrapping options.
TimeSelect: Specialized time selection component built on Select, supporting controlled/uncontrolled usage, freeform input, locale/timezone awareness, and step-based time increments. Ideal for time-based form inputs.
ToggleDetails: Collapsible content component with configurable expansion, icon positioning, sizing variants, and fluid width options. Supports controlled behavior and custom summary formatting with text components.
ToggleGroup: Enhanced toggle component with separated summary/toggle button, built-in padding/borders, and nesting support. Features custom icons, transition control, and expanded state management.
Tooltip: Contextual text overlays triggered by hover/focus, featuring placement options, color variants, and controlled/uncontrolled behavior. Designed for non-focusable content with comprehensive accessibility support.
TopNavBar: A responsive navigation bar component for site branding, navigation, user actions, and login. Adapts to small screens by truncating items and supports desktop and mobile layouts. Includes sections for brand, breadcrumbs, menu items, action items, and user controls.
Tray: A slide-out container triggered by click, appearing from top/bottom/start/end of viewport. Used for actionable content that doesn't require a modal overlay. Supports various sizes and placements with accessibility focus management.
TreeBrowser: A keyboard-accessible tree structure component for browsing hierarchical content. Supports custom icons, sorting, state management, and customizable node content. Not intended for site navigation.
TruncateText: Component for truncating text content with single or multiple line support. Supports custom ellipsis, truncation position (end or middle), and tooltips for full text accessibility. Not for buttons or navigation items.
ContextView: A container that renders inline with an arrow pointing to another element. It displays contextual information without being a popover. Supports padding, text alignment, and margin customization. Often used with components like RangeInput and internally by Popover.
View: The foundational visual component providing styling for backgrounds, borders, shadows, positioning, and focus states. Supports visual debugging and semantic HTML elements via the 'as' prop.

Utilities

BaseButton: Low-level utility component for composing Instructure UI buttons. Not intended for direct use; developers should use Button, CloseButton, IconButton, or CondensedButton instead.
Dialog: A utility component for accessibility in modals, popovers, and trays. Manages focus trapping, screen reader visibility, and keyboard navigation. Essential for WCAG-compliant modal interactions.
Expandable: Handles expand/collapse functionality for components like ToggleDetails and ToggleGroup. Provides props for accessibility and event handling. Manages state for expanded content visibility.
Focusable: A utility component that detects when elements receive focus. Provides render props for creating accessible focus-based interactions, such as skip-to-content links or focus-triggered tooltips. Ensures WCAG compliance for focus management.
Transition: A wrapper component for transitioning elements in and out of the UI. Supports fade, scale, and slide transitions with customizable directions. Handles mount/unmount transitions and supports RTL mirroring for slide animations.
Options: A view-only component for building option lists or menus. Supports variants (default, highlighted, selected, disabled), icons, nesting, and custom roles. Does not manage state—requires external event handling.
Mask: A component that covers its nearest positioned parent element. Can be used fullscreen within a Portal and supports click-to-close functionality. Useful for overlays and blocking UI interactions.
Portal: Renders a React subtree into a different DOM element. Useful for modal-like components that need to break out of parent containers. Typically used with Overlay, Modal, or other components that need to render outside their parent hierarchy.
Position: Positions content relative to a target element with various placement options. Supports RTL internationalization, offset adjustments, and mounting in specific DOM nodes. Replaces older Target/Content pattern with renderTarget prop.
Selectable: Low-level utility for building custom combobox widgets. Provides ARIA-compliant prop getters and state management hooks. Use existing Select component when possible.
InlineSVG: Renders accessible SVG content inline with support for fixed dimensions or container filling. Differentiates from SVGIcon by being suitable for non-icon SVG graphics while maintaining accessibility standards.
SVGIcon: Renders accessible inline SVG icons. Supports custom sizing, color theming, rotation, and display properties. Accepts SVG content via children or external source strings.
TruncateList: A utility component that truncates items when space is limited, commonly used in navigation bars. Controls visible item count and provides dropdown for hidden items with customizable spacing and menu triggers.

Contexts

ApplyLocale: Sets locale and timezone context for child components like TimeSelect. Enables internationalization by providing consistent localization settings throughout the component tree.
DeterministicIdContextProvider: Deprecated utility component for providing deterministic ID context. Do not use the instanceCounterMap prop. Part of InstUISettingsProvider infrastructure.

AI Components

AiInformation: Displays AI-related data in Instructure products. Composed from NutritionFacts and DataPermissionLevels components with prefixed APIs. Supports fullscreen modals for mobile viewports with comprehensive data structure for AI feature information.
DataPermissionLevels: Displays AI-related data permissions in Instructure products. Shows hierarchical permission levels with titles and descriptions. Includes a modal interface with close functionality and supports highlighting specific levels for emphasis.
NutritionFacts: A specialized modal component for displaying AI-related data in structured blocks. Includes model info, privacy/compliance details, and output metrics. Features a trigger button and modal presentation.

using-instui