Adaptly - The AI-Adaptive UI Library for React & Next.js

Adaptly: An open-source React library that uses GenAI to make your UI adapt intelligently to context and intent.

Comment

Inspiration

Most apps today ship a single, static UI to everyone, then patch in personalization later through feature flags or user scripts. We wanted a lightweight, composable way to make React interfaces truly adaptive—able to change in real time based on user intent, context, and preferences. With Gemini’s language understanding, we saw an opportunity to let UIs respond intelligently to natural input. Intent is never fixed, so the interface shouldn’t be either.

What it does

Adaptly is an open-source library for building AI-adaptive UIs in React and Next.js. It enables developers to define how the interface reacts to user intent, entirely through configuration and context rather than manual state logic.

Core capabilities

  • Adaptive Context Providers (AdaptlyProvider, AdaptiveUIProvider) manage adaptive behavior globally.

  • Adaptive Building Blocks:

    • AdaptiveCommand routes intent (via Gemini) through a command palette or input interface.
    • AdaptiveGrid dynamically rearranges components based on modes, context, or AI-inferred goals.

  • Declarative Registry (adaptly.json) that describes components, signals, and adaptive modes like Focus or Research.

  • Gemini Provider Integration to interpret user intent, context, and preferences from natural language input and map them to UI policies.

  • Persistent Storage for notes, tasks, and settings, with real-time adaptive updates and zero reloads.

For instance, switching to Focus Mode surfaces the Timer and TaskList, minimizes the NoteCard, and simplifies layout density. Research Mode surfaces WeatherWidget and NoteCard, condenses metrics, and adjusts layout emphasis—all through Gemini-driven interpretation.

How we built it

  • Core library (adaptly-lib/) written in TypeScript with modular React primitives.

    • Providers: adaptly-provider.tsx, adaptive-ui-provider.tsx
    • Adaptive UI: adaptive-grid.tsx, adaptive-command.tsx, shared components under ui/
    • Services:
    • registry-service.ts – component and mode definitions
    • storage-service.ts – persistent state
    • llm-service.ts – Gemini-powered intent understanding
    • Utilities: logger.ts, types.ts, loading-overlay.tsx

  • Examples (examples/) built with Next.js, wired to real adaptly.json registries and Gemini prompts.

  • Build & Tooling: Rollup for library bundling, Next.js for examples, fully typed with TypeScript.

Conceptually, given user signal vector s and mode m, Adaptly computes a UI policy π mapping components c to states σ: [ \pi(c \mid s, m) \to \sigma \in {\text{show, hide, emphasize, condense}} ] Gemini provides semantic interpretation to compute π dynamically and contextually.

Challenges

  • Designing the registry structure: Finding the right schema for adaptly.json that balances expressiveness, simplicity, and scalability took several iterations. We wanted it to describe components, modes, and capabilities without becoming overly verbose or fragile.
  • Resolving cross-dependencies: Ensuring that adaptive behaviors, storage layers, and Gemini intent routes worked together without circular imports or state conflicts was surprisingly tricky, especially across multiple providers.
  • Maintaining deterministic UI updates with Gemini in the loop: Integrating Gemini’s flexible natural language outputs while keeping predictable, testable UI behavior required careful policy constraints and fallbacks.
  • Optimizing adaptive state synchronization: Keeping SSR (server-side rendered) and CSR (client-side rendered) states in sync in Next.js while preserving adaptive context introduced hydration challenges.
  • Establishing solid documentation: Writing clear, developer-friendly docs for the library, registry format, and example apps was time-consuming but essential for open-source usability.
  • Ensuring accessibility and usability: Adaptive transitions, focus management, and the command palette needed to remain screen-reader compatible and visually consistent across modes.

Accomplishments

  • Seamless Gemini API integration for natural-language-based adaptation.
  • A minimal, composable API with clear primitives—provider, grid, command, and registry.
  • Real-time UI reconfiguration without reloads or rebuilds.
  • Fully typed architecture that simplifies extension and reduces integration risk.
  • Example demos showing immediate practical use in dashboards and productivity tools.
  • Published developer documentation and examples to help teams get started quickly.

What we learned

  • Gemini excels at converting user intent into structured actions, especially when paired with declarative schemas.
  • Config-driven design drastically lowers the barrier to adaptive interfaces.
  • Local-first policies ensure responsiveness, while Gemini enriches context intelligently.
  • Guardrails and good defaults are essential for predictable adaptive UX.

What’s next for Adaptly

Our goal is to grow Adaptly into a fully featured, production-ready open-source toolkit for adaptive UIs. We’re focusing on:

  • Workflow Optimization: refining build pipelines, modular mode handling, and registry caching.
  • More Examples and Recipes: adaptive dashboards, document editors, and onboarding flows.
  • Enhanced Customization: theme density, motion presets, and granular adaptive signals.

  • CLI Tooling: a dedicated Adaptly CLI to

    • scaffold new adaptive projects,
    • validate registry files,
    • auto-generate registry schemas from existing components, and
    • run local adaptation previews.

  • Expanded Gemini Providers: deeper integrations for reasoning, summarization, and multi-turn adaptive flows.

  • Community Growth: improving docs, adding playground demos, and encouraging open-source contributions.

Share this project:

Updates