ThemeProvider

ThemeProvider é dono da preferência de cores do documento. Coloque um na raiz da aplicação e decida entre light, dark ou system; um provider aninhado ainda escreve no mesmo documento.

Exemplos

Uma preferência salva

Um controle deve definir uma escolha explícita, não inverter um estado desconhecido. Esta prévia usa seu próprio storageKey, então experimentá-la não substitui a preferência salva do site de documentação.

Seguindo o sistema operacional

system é o padrão. Ele resolve um tema claro ou escuro concreto e acompanha uma mudança no sistema operacional, preservando system como a escolha salva da pessoa.

Quando usar

Use ThemeProvider uma vez na raiz da aplicação quando o modo de cores for uma preferência durável. Use o mesmo storageKey no script bloqueante de primeira pintura e no provider, ou a página pode piscar um tema antes de o React aplicar outro.

Prefira outro caminho quando:

O produto não tem modo de cores selecionável pela pessoa — defina data-theme no shell do documento e não adicione um controle de preferência.
A identidade visual, e não o modo de cores, muda por tenant — use o guia White-label e passe brand pela configuração do tenant.

Acessibilidade

ThemeProvider não emite landmark, role ou atributo ARIA. Ele define data-theme em <html> e, quando informado, data-brand.
Um controle de modo de cores é UI do consumidor: use um Button nativo ou outro controle nomeado, mantendo-o na ordem normal de tabulação.
Mudar o tema não move o foco. Não substitua o controle focado ao aplicar a nova preferência.
Nunca use cor como único sinal do modo selecionado; exponha a escolha atual no texto ou no estado do controle.

API e código

Blade: Blade não tem forma de provider. O tema vive na diretiva @lyraThemeScript e no store de tema do Alpine.

Nome	Tipo	Obrigatória	Descrição
`defaultTheme`	`Theme`	—	Theme to use when nothing is stored yet. Default: `"system"`.
`storageKey`	`string`	—	localStorage key holding the choice. Default: `"lyra-theme"`.
`brand`	`string`	—	Sets `data-brand` on `<html>` for white-label theming. See the white-label guide.
`children`	`ReactNode`	Obrigatória

$store.theme

Membro	Tipo	Obrigatória	Descrição
`theme`	`Theme`	Obrigatória	The chosen theme, which may be `"system"`.
`resolvedTheme`	`ResolvedTheme`	Obrigatória	The actual theme applied to `<html data-theme>`.
`dark`	`boolean`	Obrigatória	Convenience for `resolvedTheme === "dark"`.
`init`	`(): void`	Obrigatória	Initializes browser state after Alpine registers this singleton store.
`setTheme`	`(next: Theme): void`	Obrigatória	Chooses a theme, persists it, and applies it to the document.
`toggle`	`(): void`	Obrigatória	Flips from the theme currently applied to the document.

ThemeProvider é comportamento de React, mas o atributo resultante no documento é HTML puro. As classes da folha de estilos passam então a resolver contra o conjunto de tokens selecionado:

html

<html data-theme="dark">
  <body>
    <button class="lyra-btn lyra-btn--primary lyra-btn--md" type="button">Salvar alterações</button>
  </body>
</html>