Core

Provides the necessary theming context for all components.

Emotion

Emotion's core components and utilities are exposed to ensure a single version is bundled with the design system and the consuming application: css, jsx (most common), plus keyframes (CSS animations), Global (global styles) and ClassNames (for interop with libraries that need a plain class name rather than a css prop). See Emotion's own docs for their APIs.

Core component

The Core component provides the default styles along with CSS normalize. You should wrap your entire application in this component.

<Core>
  {/* app content */}
</Core>

Custom link component

The linkComponent prop allows you to customise the rendering of Balance links (e.g. TextLink) across an entire application. This is useful for client-side routing, handling analytics, etc.

When defining a custom link component, ensure you’re using forwardRef, otherwise certain link usages will be unable to function correctly.

If you want to make use of this mechanism within your own components, use Link which simply forwards your custom link component internally.

import React, { forwardRef } from 'react'
import { Link } from '@tanstack/react-router'
import { Core } from '@balance-web/core'

// First create the custom link
const CustomLink = forwardRef(({ href, ...props }, ref) =>
  href[0] === '/' ? (
    <Link ref={ref} to={href} {...props} />
  ) : (
    <a ref={ref} href={href} {...props} />
  )
)

// Then pass it to Core
export const App = () => (
  <Core linkComponent={CustomLink}>
    ...
  </Core>
)

If you're building your own component that needs to render a link, read the configured component with useLinkComponent rather than reaching for <a> directly:

import { useLinkComponent } from '@balance-web/core';

const MyLink = (props) => {
  const LinkComponent = useLinkComponent();

  return <LinkComponent {...props} />;
};

Data attributes

Many Balance components accept a data prop — an object of attribute name/value pairs — instead of exposing individual data-* props directly. buildDataAttributes turns that object into real data-* attributes; pass its result straight onto the underlying element.

import { buildDataAttributes } from '@balance-web/core';
import type { WithDataAttributeProp } from '@balance-web/core';

buildDataAttributes({ testid: 'save-button', tracking: 'primary-cta' });
// => { 'data-testid': 'save-button', 'data-tracking': 'primary-cta' }

WithDataAttributeProp<Props> adds the typed data?: DataAttributeMap prop to your own component's prop type. getTestIdFromDataAttributes reads the testid value back out of an already-built attribute map.

Portal parenting

Components that render into a portal (Popover, Dropdown, Modal, …) resolve where to mount via resolvePortalParent(), which returns the actual DOM element to portal into — falling back to document.body if nothing else has been configured. It also correctly finds elements inside a Shadow DOM, which a plain document.querySelector cannot reach.

getPortalParentSelector (returns a selector string rather than an element) is deprecated in favour of resolvePortalParent.

Other exports

• useCore — reads the context Core provides (currently just an internal fastMode flag); most components won't need this directly.
• CoreContext — the raw context useCore reads. Re-providing it (<CoreContext.Provider value={{ fastMode }}>) overrides fastMode for every useCore consumer (e.g. Combobox, Tooltip) in that subtree — useful for an app that only knows its own fast-mode preference once some context above Core itself (auth, book selection, …) has resolved.
• ResponsiveProp<T> — the generic type behind every component's responsive array props (e.g. padding={['xsmall', 'small', 'medium']}): T or a readonly array of T | null, one entry per breakpoint.
• CSSObject — re-exported from Emotion, for typing a component's css prop without adding a separate Emotion dependency.