Primeros pasos

Tres pasos: instalar, envolver tu app en UIProvider y después importar componentes. Omitir el paso 2 es la forma más común de romper orn-ui — cada hook y cada componente lee el theme, los íconos y los labels desde ahí.

1. Instalación

El paquete completo, o solo los componentes que necesites mediante el CLI (la segunda opción no agrega dependencia npm — consulta el comando específico en cada página de componente).

pnpm add orn-ui

npx orn-ui add button

Compatibilidad

Verificado en Expo SDK 54, 55, 56 y 57 — en los cuatro, no solo en el más nuevo. Cada SDK corre en su propio sandbox con el react-native y el react exactos de esa versión, y ahí se ejecutan el chequeo de tipos y la suite de tests completa, en CI. React Native puro funciona igual: nada de la librería importa Expo.

Expo SDK	react-native	react
54	`0.81.5`	`19.1.0`
55	`0.83.10`	`19.2.0`
56	`0.85.3`	`19.2.3`
57	`0.86.2`	`19.2.3`

Declarados como peerDependencies: react-native >=0.81.0 y react >=19.1.0. react-native-safe-area-context >=5.4.0 es opcional — solo lo importa orn-ui/safe-area.

No hace falta build nativo: orn-ui no trae módulos nativos, así que corre dentro de Expo Go en todos los SDK de la tabla.

2. Envuelve tu app en UIProvider

UIProvider es el único punto de entrada de la librería. Resuelve el theme activo (del sistema o por override manual) e inyecta íconos, insets de safe area y labels por defecto a todo el árbol. Móntalo una sola vez, por encima de tu navigator — la raíz de App.tsx es el lugar habitual.

import { UIProvider } from 'orn-ui';

export default function App() {
  return (
    <UIProvider>
      {/* your navigator / screens go here */}
    </UIProvider>
  );
}

Todo componente y hook de orn-ui (useColors, useTheme, Button, Input, todos) lanza "this hook must be used within a <UIProvider>" si se renderiza fuera de uno. No hay fallback ni valor por defecto silencioso — falla de forma explícita en runtime, no en build.

Props de UIProvider

Nombre	Tipo	Por defecto	Descripción
`children`	`React.ReactNode`	—	Tu app — montado una sola vez, arriba del navigator.
`theme?`	`ThemePair`	defaultTheme	Par light/dark. Se crea con createTheme().
`defaultMode?`	`'system' \| 'light' \| 'dark'`	'system'	Modo inicial, no controlado.
`mode?`	`'system' \| 'light' \| 'dark'`	—	Modo controlado — pásalo junto a onModeChange para manejarlo tú.
`onModeChange?`	`(mode: ThemeMode) => void`	—	Se llama al togglear, cuando mode es controlado.
`icons?`	`IconRenderer`	renderDefaultIcon	Renderer de íconos. Por defecto usa los glifos zero-dep incluidos.
`insets?`	`EdgeInsets`	zeroInsets	Insets de safe area, típicamente de useSafeAreaInsets().
`labels?`	`Partial<Labels>`	defaultLabels	Sobreescribe cualquier string interno (Close, Cancel, Search…).
`allowFontScaling?`	`boolean`	false	Apagado por defecto, para paridad en toda la librería.

Recomendado: SafeAreaUIProvider

UIProvider deja los insets en {top:0,bottom:0,left:0,right:0} por defecto — inofensivo hasta que abres un Modal fullScreen (se mete debajo del notch) o un BottomSheet (queda pegado a la barra de gestos). SafeAreaUIProvider es UIProvider con useSafeAreaInsets() ya conectado — úsalo en lugar de UIProvider y este problema queda resuelto.

Vive en su propio subpath (orn-ui/safe-area) a propósito: es el único archivo de la librería que importa un paquete de terceros (react-native-safe-area-context). Nada del entry principal de orn-ui lo referencia, así que un import { Button } from 'orn-ui' normal nunca lo resuelve — el resto de la librería sigue sin dependencias.

Necesita react-native-safe-area-context como peer (opcional — solo hace falta si usas este import):

pnpm add react-native-safe-area-context

import { SafeAreaUIProvider } from 'orn-ui/safe-area';

export default function App() {
  return (
    <SafeAreaUIProvider>
      {/* your navigator / screens go here */}
    </SafeAreaUIProvider>
  );
}

¿Tu app ya monta un <SafeAreaProvider> más arriba (algunas plantillas de React Navigation lo hacen)? Pasa mountSafeAreaProvider={false} — un provider anidado mide el frame de su propia View, no el de la ventana, así que dentro de él los insets dan cero.

SafeAreaUIProviderProps

Además de todas las props de UIProvider indicadas arriba, excepto insets (se sigue aceptando, pero es opcional — sobrescribe el valor medido en lugar de ser obligatoria).

Nombre	Tipo	Por defecto	Descripción
`insets?`	`EdgeInsets`	measured via useSafeAreaInsets()	Override explícito — gana sobre el valor medido. Útil para tests, Storybook, o una pantalla que no ocupa la ventana entera.
`mountSafeAreaProvider?`	`boolean`	true	También monta <SafeAreaProvider>. Ponlo en false si tu app ya tiene uno arriba.

3. Usa los componentes

A partir de aquí, cada página de componente de este sitio funciona tal como se muestra: copias un snippet de variante y renderiza. Consulta la lista de componentes más abajo.

Ver componentes →