So quite several application renders a list of filters applied somewhere in the UI before the data part or at least within the filter component. That being said, we are not here to discuss UI challenges, but something more fundamental, states.

How will you manage the state across multiple components? As it stands, the state is being consumed by at least three components, the actual list, the filter and the list of applied filters, and any change in the filter should affect all three.

The Concerns

If we simplify the problem statement, we are left with mainly three concerns:

1. The Data Part: How will the Data Layer know what filters are being applied and produce results accordingly?

2. The UI Part: How can the user know and apply one or more filters in the UI?

3. The Store Part: How can we sync the filter information and persist throughout the lifetime of such UI?

The Data Part

Based on how your API is designed, this can be achieved in multiple ways. In our case, we will assume we have Query Parameters over GET requests. Using native fetch we can implement the following:

export const loadUsers = (filters) => fetch(`https://api.example.com/users?${new URLSearchParams(filters)}`);

The UI Part

On the UI side, assuming we have the filter object, it is not much hard to pass them on to React Components and have the UI show which filters are available and which are already applied. I am keeping this part open-ended intentionally.

The Store Part

Now that we have sorted out two of three concerns, here comes the most important part. We know if we pass our active filters to the fetch function we will get updated results. We also are sure that if we know the filters, we can show them in the UI.

Like how we have Query Parameters for the API, what about having the same for the page? After all, it is just a medium to the back-end data service!

So we store the filter object into the URL as Parameters post serialization. And deserialize during the render. This also gives us an edge for bookmarking and sharing preferable result sets. However, given that the URL can be modified outside the scope of the application, there needs to be validation logic as well.

Let's compile all of this into a reusable React hook:

import { NextRouter, useRouter } from "next/router";
import * as React from "react";
import * as Yup from "yup";
import type Lazy from "yup/lib/Lazy";

/**
 * Available Options on Validation Schema.
 */
type Options<T extends Yup.AnyObjectSchema | Lazy<any>> = Parameters<
  T["validateSync"]
>[1];

/**
 * Query Filter Result Interface.
 */
type QueryFilterResult<T extends Record<string, any>> = {
  /**
   * Validation error on Filter Key Value pairs.
   */
  errors: Partial<T>;
  /**
   * Filter results using one or more Parameter.
   * @param filters - A Key Value pair of Filter Names and Values.
   */
  filterBy(filters: Partial<T>): Promise<void>;
  /**
   * Key Value pair of applicable Filters.
   */
  filters: T;
  /**
   * Reset Filters.
   */
  reset(filters?: Partial<T>): Promise<void>;
};

/**
 * Mutable Ref Object to hold current values of Filter and Validation Errors.
 */
type QueryFilterRef<T> = {
  /**
   * Validation error on Filter Key Value pairs.
   */
  errors: Partial<T>;
  /**
   * Key Value pair of applicable Filters.
   */
  values: T;
};

/**
 * Query Filter Interface.
 */
type QueryFilter = <T extends Yup.AnyObjectSchema | Lazy<any>>(
  /** Yup Schema of the Query Filters. */
  schema: T,
  /** Additional Schema Options for Validation. */
  options?: Options<T>,
) => QueryFilterResult<Yup.InferType<T>>;

/**
 * Push onto History Stack with Query Parameters.
 * @param router - Next Router Instance.
 * @param queryParams - Query Parameters.
 */
const pushStateWithQuery = <T extends Record<string, any>>(
  router: NextRouter,
  queryParams: T,
) => {
  const url = `${router.pathname}?${new URLSearchParams(queryParams)}`;
  return router.push(url, undefined, { scroll: false, shallow: true });
};

/**
 * Transforms Yup Validation Error to Serialsed Schema.
 * @param error - Yup Error Object.
 * @returns Seralised Error Object.
 */
const parseYupError = (error: Yup.ValidationError) => {
  if (!error.inner.length) {
    return {
      [error.path!]: error.errors[0],
    };
  }

  return (error.inner || []).reduce<Record<string, string>>(
    (previous, error) => {
      if (!previous[error.path!]) {
        previous[error.path!] = error.message;
      }

      return previous;
    },
    {},
  );
};

/**
 * Default Parameters for Schema Validation Options.
 */
const BaseSchemaOptions: Partial<Options<Yup.AnyObjectSchema | Lazy<any>>> = {
  abortEarly: true,
  stripUnknown: true,
} as const;

/**
 * Validates a given object against provided Schema and Schema Options.
 * @param object - Instance of Object that requires Validation.
 * @param schema - Schema to Validate against.
 * @param options - Schema Validation Options.
 * @returns An Object with Parsed Values and Validation Errors.
 */
const validateYupSchema = <
  T extends Yup.AnyObjectSchema | Lazy<any>,
  O extends Record<string, any>,
>(
  object: O,
  schema: T,
  options: Options<T>,
): QueryFilterRef<Yup.InferType<T>> => {
  try {
    return {
      values: schema.validateSync(
        object,
        Object.assign(BaseSchemaOptions, options),
      ),
      errors: {},
    };
  } catch (error) {
    return {
      values: {},
      errors: parseYupError(error as Yup.ValidationError) as Partial<
        Yup.InferType<T>
      >,
    };
  }
};

/**
 * Create Filters out of Query Parameters in current Page.
 * @param schema - Yup Schema of the Query Filters.
 * @param options - Additional Schema Options for Validation.
 * @returns Parsed Filters, callback to update Filters and Error Object in case of validation error.
 */
export const useQueryFilter: QueryFilter = (schema, options) => {
  type Schema = Yup.InferType<typeof schema>;

  const router = useRouter();

  const filtersRef = React.useRef<QueryFilterRef<Schema>>({
    values: {},
    errors: {},
  });

  filtersRef.current = validateYupSchema(router.query, schema, options);

  /** Cleanup Query Parameters */
  useInsertionEffect(() => {
    const { values: filters } = filtersRef.current;
    pushStateWithQuery(router, filters);
  }, []);

  const filterBy = React.useCallback(async (filters: Partial<Schema>) => {
    /** This avoids Stale Closure problem by using Mutable Ref instance. */
    const { values: _filters } = filtersRef.current;
    const nextFilters = {
      ..._filters,
      ...filters,
    };

    const pushStatePromise = pushStateWithQuery(router, nextFilters);

    /** This ensures consecutive call of `filterBy` does not reset earlier filters. */
    filtersRef.current = {
      errors: {},
      values: nextFilters,
    };

    /** This is useful for chaining promises in consumer component or hook. */
    await pushStatePromise;
  });

  const reset = React.useCallback(async (filters: Partial<Schema> = {}) => {
    const pushStatePromise = pushStateWithQuery(router, filters);

    /** This ensures subsequent call of `filterBy` does not reuse earlier filters. */
    filtersRef.current = {
      errors: {},
      values: filters,
    };

    /** This is useful for chaining promises in consumer component or hook. */
    await pushStatePromise;
  });

  const { values: filters, errors } = filtersRef.current;

  return {
    errors,
    filterBy,
    filters,
    reset,
  };
};

That is it. Now you have a React hook managing your state, and on the consumer side, you can use the current state to manage and update the result set and show them in your UI.

TLDR; Experienced React developers can skip directly to the Let's Get Started chapter.

How React Works in Browser

Before we get started with the nitty-gritty implementation details of the topic. Let us take a moment and understand how the React libraries work under the hood to build the UI we declared in our codebase.

In our codebase, a React component might look like this:

import React from "react";

export const HelloWorldComponent = () => <h1>Hello World</h1>;

And we might be rendering this into UI as follows, assuming we have an empty div with the id "app":

import React from "react";
import ReactDOMClient from "react-dom/client";

import { HelloWorldComponent } from "./HelloWorld";

const appContainer = document.getElementById("app");
const appRoot = ReactDOMClient.createRoot(appContainer);

appRoot.render(<HelloWorldComponent />);

Now underneath the hood, React will create the required element tree and append it to the aforesaid div. The purpose of ReactDOM here is to reflect all our declarative UI mapping into actual DOM elements.

Module Bundlers

It would not be an overstatement to say front-end state of art applications as we see them today might not have existed if not for high-end module bundlers like Webpack, Rollup, Turbopack, Vite etc. The core purpose of these tools is to convert a set of source files from the developer workspace into a couple of executable files for the staging/production environment, e.g., a browser.

One of the key file these module bundlers generate is the Manifest file. This file is responsible to provide metadata to the runtime so that the runtime can load the entry point and dependencies as they are needed. Webpack generates a file called asset-manifest.json which holds information on the mapping between source files and runtime assets and a list of entry points.

Let's Get Started

We start our journey by creating a factory function that will be exposed to the outside world. For the sake of simplicity, let us assume we want to make this function available in the global scope. This pattern can be improved using custom loaders, but we can skip it for the time being.

import { Component, ComponentProps } from "components";
import * as ReactDOMClient from "react-dom/client";

/**
 * Factory Method for React Component.
 * @param container DOM Container to render React Component.
 * @param props Incoming Props for React Component.
 * @returns Object with a handler to unmount React Component from the DOM.
 */
export const ComponentFactory = (container: Element, props: ComponentProps): VoidFunction => {
  const root = ReactDOMClient.createRoot(container, { identifierPrefix: "react" });
  root.render(<Component {...props} />);

  return {
    destroy: () => root.unmount(),
  };
};

Once went through the build pipeline, this yields main_[contenthash].js file which would be the entry point of our application, considering everything inside the Component is valid.

The Middleware House

Now we have two problems at hand, one is to tell Django that we have to load runtime assets generated by our module bundler, Webpack in this case; and invoke the factory function from the current system with proper parameters to create the UI. Let's take the first one for a spin.

# Standard library imports.
import json
import re
from typing import Any, Callable, Dict, List, Union

# Valid Keys in Asset Manifest JSON Type Alias.
AssetManifestKeys = Literal["entrypoints", "files"]


class AssetManifest:
    """
    Asset Manifest Class
    """

    files: Dict[str, str]
    """
    Mapping between Original Filenames and their Artifact Name (appended by content-hash for caching purposes).
    """
    entrypoints: List[str]
    """
    List of files that needs to loaded by the Page to start Client application.
    """

    def __init__(self, decoded_json: Dict[AssetManifestKeys, Any]) -> None:
        """
        Constructor method for Asset Manifest Class.
        """
        self.entrypoints = decoded_json["entrypoints"]
        self.files = decoded_json["files"]


# Default Callbale to parse JSON String.
WHITESPACE = re.compile(r"[ \t\n\r]*", re.VERBOSE | re.MULTILINE | re.DOTALL)


class AssetManifestDecoder(json.JSONDecoder):
    """
    JSON Decoder Class to Parse JSON String into Asset Manifest Class instance.
    """

    def decode(self, s: str, _w: Callable[..., Any] = WHITESPACE.match) -> AssetManifest:
        """
        Return the Asset Manifest class instance of ``s`` (a ``str`` instance
        containing a JSON document).
        """
        decoded_json: Dict[AssetManifestKeys, Any] = super().decode(s, _w)
        asset_manifest = AssetManifest(decoded_json)
        return asset_manifest


# Valid File Name/Descriptor Type Alias.
StrOrBytes = Union[str, bytes]
StrOrBytesPath = Union[StrOrBytes, PathLike[str], PathLike[bytes]] OpenFile = Union[StrOrBytesPath, int]  # noqa: Y026


def load_asset_manifest(filepath: OpenFile) -> AssetManifest:
    """
    Helper Function to load Module Bundler (like Webpack, Rollup etc.) generated Asset Manifest.
    """
    with open(filepath, "r") as fp:
        return json.load(fp, cls=AssetManifestDecoder)


def parse_asset_manifest(strOrBytes: StrOrBytes) -> AssetManifest:
    """
    Helper Function to parse Module Bundler (like Webpack, Rollup etc.) generated Asset Manifest.
    """
    return json.loads(strOrBytes, cls=AssetManifestDecoder)

Here we have developed our custom JSON Decoder that serializes a JSON string into an AssetManifest object. The function parse_asset_manifest can be tested in isolation for validation, however, we would be using the load_asset_manifest function more often. Provided we can configure the destination directory for Webpack to emit the manifest file, the actual file path can be given through environment variables.

Now let's create a mixin that composes this middleware and simplifies the integration process.

class ReactViewMixin(TemplateView):
    """
    Mixin that helps loading React assets into Server-side HTML.
    This should add `react_assets` property to context data which then to be added into `<script>` tag.
    """

    def get_context_data(self, **kwargs: Any) -> Dict[str, Any]:
        """
        Overwrite Context Data to hold static assets required to load React Component in the UI.
        """
        context_data = super().get_context_data(**kwargs)
        asset_manifest = load_asset_manifest(settings.REACT_ASSET_MANIFEST_PATH)
        context_data["react_assets"] = asset_manifest.entrypoints
        return context_data

Now we can simply inherit any Django View from here and it will work out of the box.

Bootstrapping in Browser

First of all, we need to add <script> tags for React resources into our view templates.

{% for asset in react_assets %}
  <script type="application/javascript" defer="" src="/{{ asset }}"></script>
{% endfor %}

I believe here on, figuring out the rest is quite easy. We will have an empty div and will pick that element once the document is ready and invoke the factory function with proper parameters.

<div id="id_react_app"/>
<script>
$(document).ready(function() {
  var $container = $("#id_react_app");
  var container  = $container.get(0);

  var ref = ComponentFactory(container, {
    onMount: () => console.log("React Component Mounted!"),
  });

  $(window).on("beforeunload", ref.destroy());
</script>

Conclusion

So it turns out, despite sounding unorthodox, it is possible to integrate a React UI system into an existing one and could be a potential choice that saves some $$ for the business.