API Reference#

Complete reference for @bsky.app/alf. All exports come from a single entry point:

import {
  atoms,
  useTheme,
  Provider,
  Context,
  tokens,
  utils,
  themes,
  createTheme,
  createThemes,
  DEFAULT_PALETTE,
  DEFAULT_SUBDUED_PALETTE,
  invertPalette,
  isWeb,
  isNative,
  isIOS,
  isAndroid,
  isFabric,
  web,
  native,
  ios,
  android,
  platform,
} from '@bsky.app/alf'

import type {
  Palette,
  Theme,
  ThemeScheme,
  ThemeName,
  ThemeAtoms,
  TextStyleProp,
  ViewStyleProp,
} from '@bsky.app/alf'

Provider and Hook#

Provider#

React context provider that makes the active theme available to all children via useTheme().

<Provider activeTheme="light" themes={themes}>
  <App />
</Provider>

The provider memoizes the context value based on activeTheme and themes.

useTheme()#

Returns the active Theme object from context. You access theme-aware color atoms from t.atoms:

const t = useTheme()
<View style={[t.atoms.bg, t.atoms.shadow_md]}>
  <Text style={[t.atoms.text]}>Themed text</Text>
</View>

Returns: Theme

Context#

The raw React context (React.Context<{ theme: Theme }>). Initial value uses themes.light. Display name: 'AlfContext'.

You rarely need this directly. Use useTheme() instead.

Atoms#

All atoms live on the atoms object. They are frozen, static style objects that you combine via arrays.

import { atoms as a } from '@bsky.app/alf'

<View style={[a.flex_row, a.gap_md, a.p_lg, a.rounded_md]} />

Naming conventions#

• Underscore prefix for sizes starting with a number: _2xs, _2xl, _3xl, etc.
• Axis suffixes: x (left + right), y (top + bottom)
• Side suffixes: t (top), b (bottom), l (left), r (right)

Debug#

Positioning#

Z-index#

Overflow#

Width and height#

Border radius#

Values come from tokens.borderRadius (zero variants use literal 0).

Flexbox#

Alignment#

Gap#

Values come from tokens.space (zero variants use literal 0).

Typography#

Font size#

Each atom sets both fontSize and letterSpacing: 0. Values come from tokens.fontSize.

Text alignment#

Line height#

Values are unitless multipliers from tokens.lineHeight. Use the utils.leading() function when you need computed pixel values on native.

Letter spacing#

Font weight#

Font style#

Borders#

On native, all 1px border atoms use StyleSheet.hairlineWidth instead. See the platform behavior section.

Border width#

Border color#

For theme-aware border colors, use t.atoms.border_contrast_low, t.atoms.border_contrast_medium, or t.atoms.border_contrast_high.

Border curves (iOS only)#

These resolve to empty objects {} on web. On native, they use the ios() platform selector, returning the style on iOS and undefined on Android.

Shadows#

Static shadow atoms are empty objects on web and Fabric. Use theme shadow atoms (t.atoms.shadow_sm, etc.) for cross-platform shadows with proper theme colors.

Gutters#

Semantic padding shortcuts. Each has _x (horizontal) and _y (vertical) variants.

Padding#

Values come from tokens.space (zero variants use literal 0). Each size has p_, px_, py_, pt_, pb_, pl_, pr_ variants.

Full atom names follow the pattern: p_md, px_lg, py_sm, pt_xl, pb_2xl, pl_xs, pr_3xl.

Margin#

Values come from tokens.space (zero variants use literal 0). Each size has m_, mx_, my_, mt_, mb_, ml_, mr_ variants.

Full atom names follow the pattern: m_md, mx_lg, my_sm, mt_xl, mb_2xl, ml_xs, mr_3xl.

Auto margins: m_auto, mx_auto, my_auto, mt_auto, mb_auto, ml_auto, mr_auto.

Pointer events and user select#

Text decoration#

Display#

Cursor#

Theme Atoms#

These live on t.atoms (where t = useTheme()). They adapt to the active theme's color palette.

Theme atoms only cover the contrast color scale — the neutral grays used for text, backgrounds, and borders on nearly every component. Primary, positive, and negative colors are more situational, so they are accessed directly from the palette instead:

const t = useTheme()

// Contrast colors → theme atoms
<View style={[t.atoms.bg, t.atoms.border_contrast_medium]}>
  <Text style={[t.atoms.text]}>Neutral text</Text>
</View>

// Primary / positive / negative → palette
<View style={{ backgroundColor: t.palette.primary_500 }}>
  <Text style={{ color: t.palette.positive_500 }}>Success</Text>
</View>

Palette values still adapt to the active theme automatically via invertPalette(), so t.palette.primary_500 returns the correct shade in light, dark, and dim modes.

Text#

Background#

Border#

Shadow#

Shadow atoms include native shadow props and a boxShadow CSS string for web. Light themes use 0.1 shadow opacity, dark/dim themes use 0.4.

Tokens#

Imported as a namespace: import { tokens } from '@bsky.app/alf'. All values are pixel-based numbers (no rem/em).

tokens.space#

tokens.fontSize#

tokens.lineHeight#

tokens.borderRadius#

tokens.fontWeight#

tokens.labelerColor#

tokens.TRACKING#

Letter-spacing constant. Value: 0.

Palette#

Palette type#

Defines all color values for a theme. Four color families, each with shades:

• contrast_* (neutrals): 0, 25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950, 975, 1000
• primary_* (brand blue): 25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950, 975
• positive_* (green): same scale as primary
• negative_* (red): same scale as primary

Plus white, black, and like (pink, #EC4899).

All values are CSS color strings.

DEFAULT_PALETTE#

The standard light-mode palette. Contrast ranges from #FFFFFF (0) to #000000 (1000). Primary blues range from #F5F9FF (25) to #001533 (975).

DEFAULT_SUBDUED_PALETTE#

A softer alternative used by the dim theme. Same structure, lower contrast. The darkest contrast value is #151D28 instead of pure black.

invertPalette(palette)#

Flips all four color scales (contrast, primary, positive, negative) for dark mode. Swaps _0/_25 with _1000/_975, and so on symmetrically. The _500 center values in each scale remain unchanged. Keeps white, black, and like unchanged.

const darkPalette = invertPalette(DEFAULT_PALETTE)

Returns: Palette

Themes#

Theme type#

type Theme = {
  scheme: ThemeScheme   // 'light' | 'dark'
  name: ThemeName       // 'light' | 'dark' | 'dim'
  palette: Palette
  atoms: ThemeAtoms
}

ThemeScheme#

'light' | 'dark'

ThemeName#

'light' | 'dark' | 'dim'

themes#

Pre-built theme objects, ready to pass to Provider:

themes.light  // Light scheme, DEFAULT_PALETTE
themes.dark   // Dark scheme, inverted DEFAULT_PALETTE, 0.4 shadow opacity
themes.dim    // Dark scheme, inverted DEFAULT_SUBDUED_PALETTE, 0.4 shadow opacity

createTheme({ scheme, name, palette, options? })#

Builds a Theme from a palette.

Returns: Theme

createThemes({ defaultPalette, subduedPalette })#

Builds all three theme variants at once. Inverts the palettes automatically for dark and dim.

Returns: { light: Theme, dark: Theme, dim: Theme }

Platform#

Detection booleans#

These resolve at build time via platform-split files (.native.ts vs .ts).

Platform selectors#

Identity functions that return the value on the matching platform and undefined everywhere else.

web({ cursor: 'pointer' })      // returns the object on web, undefined on native
native({ elevation: 4 })        // returns the object on native, undefined on web
ios({ borderCurve: 'continuous' })
android({ elevation: 8 })

platform(specifics)#

Works like React Native's Platform.select(). On web, returns specifics.web or specifics.default.

platform({ web: 16, default: 12 })

On web, this uses || (not ??), so falsy values like 0 or "" for specifics.web will fall through to specifics.default.

Utils#

Imported as a namespace: import { utils } from '@bsky.app/alf'.

utils.alpha(color, opacity)#

Converts a color string to a transparent variant at the given opacity (0 to 1).

utils.alpha('#FF0000', 0.5)        // '#FF000080'
utils.alpha('rgb(255, 0, 0)', 0.5) // 'rgba(255, 0, 0, 0.5)'
utils.alpha('hsl(0, 100%, 50%)', 0.5) // 'hsla(0, 100%, 50%, 0.5)'

Supported formats: #RGB, #RRGGBB, rgb(), hsl(). Returns the original color unchanged if the format is not recognized.

utils.leading(textStyle)#

Calculates a lineHeight value from a text style's fontSize and lineHeight multiplier.

utils.leading({ fontSize: 15, lineHeight: 1.5 })
// Web:    { lineHeight: '1.5' }  (unitless string)
// Native: { lineHeight: 23 }    (rounded pixel value)

Defaults to tokens.lineHeight.snug when lineHeight is missing. On native, also defaults to tokens.fontSize.sm when fontSize is missing (web does not use fontSize).

Returns: Pick<TextStyle, 'lineHeight'>

utils.select(name, options)#

Theme-aware value selector. Pass a ThemeName and an object mapping theme names to values.

utils.select('dark', {
  light: '#FFFFFF',
  dark: '#000000',
  dim: '#1A1A2E',
})
// Returns '#000000'

The type signature accepts either an exhaustive map of all three theme names, or a partial map with a default key. When using default, you still need to provide values for every theme name you want to handle — the default value only applies when the name argument falls outside the known ThemeName union (which shouldn't happen in practice). If a theme name is omitted from the options, its value will be undefined:

utils.select('dim', { light: 'white', default: 'black' })
// Returns undefined — 'dim' matches the switch case but options.dim is not set

For reliable results, always provide all three theme names:

utils.select('dim', { light: 'white', dark: 'black', dim: 'black' })
// Returns 'black'

utils.flatten(style)#

Merges a style array (or nested arrays) into a single object. Filters out falsy values.

utils.flatten([a.flex_row, a.gap_md, false && a.p_lg])
// { flexDirection: 'row', gap: 12 }

On web and native, this delegates to StyleSheet.flatten. A custom fallback implementation is provided for other environments where neither .web.ts nor .native.ts is resolved.

Returns: merged style object

Types#

TextStyleProp#

type TextStyleProp = { style?: StyleProp<TextStyle> }

ViewStyleProp#

type ViewStyleProp = { style?: StyleProp<ViewStyle> }

ThemeAtoms#

The type of t.atoms (where t = useTheme()). Maps each theme atom name to its style object.

Palette#

Color value map for a theme. See Palette for the full shape.

Theme#

Complete theme object containing scheme, name, palette, and atoms. See Themes for details.

ThemeScheme#

'light' | 'dark'

ThemeName#

'light' | 'dark' | 'dim'

Native Overrides#

When running on iOS or Android, these atoms behave differently from their web counterparts: