Interface ConsentProviderProps

Propriedades do ConsentProvider com suporte a componentes Material-UI integrados.

Remarks

Estende as props do ConsentProviderCore com valores padrão para componentes UI. Este Provider é o ponto de entrada principal para uso da biblioteca com Material-UI, oferecendo uma experiência "batteries included" (tudo pronto para uso).

Diferenças do Core

✅ Injeção automática de PreferencesModal, CookieBanner e FloatingPreferencesButton
✅ Suporte a tema Material-UI via ThemeProvider
✅ Props dedicadas para desabilitar componentes padrão
✅ Não requer configuração manual de componentes UI

Quando Usar Este Provider

Você está usando Material-UI no seu projeto
Quer começar rápido com UI pronta
Prefere defaults sensatos com possibilidade de override

Quando Usar o Core

Você quer controle total sobre a UI
Está usando outra biblioteca de UI (Chakra, Ant Design, etc.)
Prefere implementação headless

Since

0.5.0

Example: Uso básico com defaults

import { ConsentProvider } from '@react-lgpd-consent/mui'

<ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
  <App />
</ConsentProvider>

Example: Com tema customizado

import { createTheme } from '@mui/material/styles'
import { ConsentProvider } from '@react-lgpd-consent/mui'

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' }
  }
})

<ConsentProvider
  theme={theme}
  categories={{ enabledCategories: ['analytics'] }}
>
  <App />
</ConsentProvider>

Example: Desabilitando componentes padrão

<ConsentProvider
  categories={{ enabledCategories: ['analytics'] }}
  disableDefaultModal={true}
  disableDefaultBanner={true}
  disableDefaultFloatingButton={true}
>
  <App />
</ConsentProvider>

interface ConsentProviderProps {
    blocking?: boolean;
    blockingMode?: "soft" | "hard";
    blockingStrategy?: "provider" | "auto" | "component";
    categories?: ProjectCategoriesConfig;
    children: ReactNode;
    cookie?: Partial<ConsentCookieOptions>;
    CookieBannerComponent?: ComponentType<CustomCookieBannerProps>;
    cookieBannerProps?: Record<string, unknown>;
    designTokens?: DesignTokens;
    disableDefaultBanner?: boolean;
    disableDefaultFloatingButton?: boolean;
    disableDefaultModal?: boolean;
    disableDeveloperGuidance?: boolean;
    disableDiscoveryLog?: boolean;
    disableFloatingPreferencesButton?: boolean;
    FloatingPreferencesButtonComponent?: ComponentType<
        CustomFloatingPreferencesButtonProps,
    >;
    floatingPreferencesButtonProps?: Record<string, unknown>;
    guidanceConfig?: GuidanceConfig;
    hideBranding?: boolean;
    initialState?: ConsentState;
    language?: "fr" | "pt" | "en" | "es" | "de" | "it";
    onAuditLog?: (entry: ConsentAuditEntry) => void;
    onConsentChange?: (
        state: ConsentState,
        context: { origin: "banner" | "modal" | "programmatic" | "reset" },
    ) => void;
    onConsentGiven?: (state: ConsentState) => void;
    onConsentInit?: (state: ConsentState) => void;
    onConsentVersionChange?: (context: ConsentVersionChangeContext) => void;
    onPreferencesSaved?: (prefs: ConsentPreferences) => void;
    PreferencesModalComponent?: ComponentType<CustomPreferencesModalProps>;
    preferencesModalProps?: Record<string, unknown>;
    storage?: ConsentStorageConfig;
    texts?: Partial<AdvancedConsentTexts>;
    textVariant?: "formal" | "casual" | "concise" | "detailed";
    theme?: Theme;
}

Hierarchy (View Summary)

ConsentProviderProps
- ConsentProviderProps

Properties

`Optional`blocking

blocking?: boolean

Comportamento do banner de consentimento:

false (padrão): Banner não-intrusivo, usuário pode navegar livremente
true: Banner bloqueia interação até decisão (compliance rigorosa)

`Optional`blockingMode

blockingMode?: "soft" | "hard"

Intensidade do bloqueio quando blocking estiver habilitado.

'soft' (padrão): aplica apenas overlay visual (cliques bloqueados).
'hard': aplica overlay + torna o conteúdo da aplicação inerte (sem foco/teclado).

Remarks

O modo hard utiliza o atributo inert para restringir navegação por teclado ao banner/modal, atendendo contextos regulatórios mais estritos.

`Optional`blockingStrategy

blockingStrategy?: "provider" | "auto" | "component"

Estratégia de bloqueio quando blocking estiver habilitado.

'auto' (padrão):
- Se usar o banner padrão da lib, o bloqueio visual/funcional fica a cargo do próprio banner.
- Se usar CookieBannerComponent custom, o Provider NÃO cria overlay; o bloqueio fica a cargo do componente custom (compatibilidade atual).
'provider': o Provider cria um overlay de bloqueio por cima da aplicação (e abaixo do banner), garantindo que cliques sejam bloqueados, independentemente do banner custom implementar ou não esse comportamento.
'component': nenhum overlay do Provider; espera-se que o banner (padrão ou custom) trate o bloqueio.

Observações:

Visual do overlay do Provider controlado por designTokens.layout.backdrop:
- false: overlay transparente (bloqueia cliques sem escurecer — útil quando o app já possui um dark-filter visual próprio).
- string (ex.: 'rgba(0,0,0,0.4)'): overlay com escurecimento gerenciado pela lib.
A11y: recomenda-se que o banner use semântica de diálogo (role="dialog", aria-modal="true") e trap de foco.

`Optional`categories

categories?: ProjectCategoriesConfig

Configuração das categorias de cookies utilizadas no projeto. Define quais categorias padrão serão habilitadas.

Example: Apenas analytics:

categories={{ enabledCategories: ['analytics'] }}

Example: Com categoria padrão apenas:

categories={{ enabledCategories: ['analytics', 'marketing'] }}

children

children: ReactNode

Elementos filhos - toda a aplicação que precisa de contexto de consentimento.

`Optional`cookie

cookie?: Partial<ConsentCookieOptions>

Configurações do cookie de consentimento. Valores não fornecidos usam padrões seguros para LGPD.

Example

cookie={{
  name: 'meuAppConsent',
  maxAge: 60 * 60 * 24 * 180, // 180 dias
  sameSite: 'Strict',
  secure: true,
}}

`Optional`CookieBannerComponent

CookieBannerComponent?: ComponentType<CustomCookieBannerProps>

Componente customizado para substituir o banner padrão de cookies. Se não fornecido, o CookieBanner padrão será renderizado. Deve implementar a lógica de consentimento usando as props definidas em CustomCookieBannerProps.

`Optional`cookieBannerProps

cookieBannerProps?: Record<string, unknown>

Props adicionais passadas para o banner customizado (repassadas sem transformação).

`Optional`designTokens

designTokens?: DesignTokens

Tokens de design para customização visual avançada. Oferece controle direto sobre cores, fontes, espaçamento e layout.

Example

designTokens={{
  colors: { background: '#000', text: '#fff' },
  typography: { fontFamily: ''Inter', sans-serif' },
  spacing: { borderRadius: { banner: 0 } }
}}

`Optional`disableDefaultBanner

disableDefaultBanner?: boolean

Se true, desabilita a injeção automática do CookieBanner.

Remarks

Útil quando você quer uma implementação própria de banner, mantendo outras integrações (modal, botão flutuante).

Quando false (padrão), o banner padrão do MUI é renderizado automaticamente quando o usuário ainda não consentiu.

Default Value

false

Since

0.5.0

Example

function MyBanner() {
  const { acceptAll, rejectAll } = useConsent()
  return <div>Meu banner customizado</div>
}

<ConsentProvider
  disableDefaultBanner={true}
  CookieBannerComponent={MyBanner}
>
  <App />
</ConsentProvider>

`Optional`disableDefaultFloatingButton

disableDefaultFloatingButton?: boolean

Se true, desabilita a injeção automática do FloatingPreferencesButton.

Remarks

Útil quando você quer controlar completamente como usuários reacessam suas preferências (ex: link no footer, menu de configurações).

Nota: disableFloatingPreferencesButton do core também oculta o botão, mas esta prop impede completamente a renderização do componente.

Default Value

false

Since

0.5.0

Example

<ConsentProvider
  disableDefaultFloatingButton={true}
  categories={{ enabledCategories: ['analytics'] }}
>
  <App />
</ConsentProvider>

`Optional`disableDefaultModal

disableDefaultModal?: boolean

Se true, desabilita a injeção automática do PreferencesModal.

Remarks

Use isso quando quiser passar seu próprio modal via PreferencesModalComponent ou quando quiser implementação totalmente headless.

Quando false (padrão), o modal padrão do MUI é renderizado automaticamente quando o usuário clica em "Preferências" ou "Gerenciar".

Default Value

false

Since

0.5.0

Example

function MyModal() {
  const { closePreferences } = useConsent()
  return <div>Meu modal customizado</div>
}

<ConsentProvider
  disableDefaultModal={true}
  PreferencesModalComponent={MyModal}
>
  <App />
</ConsentProvider>

`Optional`disableDeveloperGuidance

disableDeveloperGuidance?: boolean

Desabilita os avisos e sugestões para desenvolvedores no console. Útil para ambientes de produção ou quando os avisos não são desejados. Por padrão, os avisos já são desabilitados em builds de produção.

`Optional`disableDiscoveryLog

disableDiscoveryLog?: boolean

Desabilita o log automático de descoberta de cookies em modo desenvolvimento. Mesmo com disableDeveloperGuidance ativado, por padrão a descoberta é logada uma vez para ajudar o mapeamento. Use esta prop para suprimir também esse log experimental.

Since

0.4.1

`Optional`disableFloatingPreferencesButton

disableFloatingPreferencesButton?: boolean

Desabilita o botão flutuante de preferências. Útil quando o usuário da lib quer ter controle total sobre o acesso às preferências.

`Optional`FloatingPreferencesButtonComponent

FloatingPreferencesButtonComponent?: ComponentType<
CustomFloatingPreferencesButtonProps,
>

Componente customizado para substituir o botão flutuante de preferências. Se não fornecido, o FloatingPreferencesButton padrão será renderizado. Deve implementar a lógica de consentimento usando as props definidas em CustomFloatingPreferencesButtonProps.

`Optional`floatingPreferencesButtonProps

floatingPreferencesButtonProps?: Record<string, unknown>

Props adicionais passadas para o botão flutuante customizado (repassadas sem transformação).

`Optional`guidanceConfig

guidanceConfig?: GuidanceConfig

Configuração avançada para o sistema de developer guidance. Permite controle granular sobre quais tipos de guias são exibidos e como.

Since

0.4.1

Example

// Usar preset de desenvolvimento
guidanceConfig={GUIDANCE_PRESETS.development}

// Configuração personalizada
guidanceConfig={{
  showWarnings: true,
  showComplianceScore: true,
  minimumSeverity: 'warning'
}}

`Optional`hideBranding

hideBranding?: boolean

Oculta o branding "fornecido por LÉdipO.eti.br" dos componentes.

`Optional`initialState

initialState?: ConsentState

Estado inicial do consentimento para hidratação SSR.

Example

// Em Next.js para evitar flash do banner
<ConsentProvider initialState={{ consented: true, preferences: {...} }}>

`Optional`language

language?: "fr" | "pt" | "en" | "es" | "de" | "it"

Idioma ativo para resolver textos via i18n (opcional). Quando definido, aplica texts.i18n[language] nos campos principais.

Default Value

'pt'

`Optional`onAuditLog

onAuditLog?: (entry: ConsentAuditEntry) => void

Callback de auditoria executado sempre que o consentimento é registrado, atualizado ou resetado. Útil para persistir logs externos (ex.: backend, data lake) com carimbo de tempo e versão do termo.

Since

0.7.0

Example

<ConsentProvider
  storage={{ namespace: 'portal.gov', version: '2025-Q4' }}
  onAuditLog={(audit) => api.auditConsent(audit)}
/>

`Optional`onConsentChange

onConsentChange?: (
state: ConsentState,
context: { origin: "banner" | "modal" | "programmatic" | "reset" },
) => void

Callback disparado sempre que o consentimento muda (banner, modal ou programático/reset).

`Optional`onConsentGiven

onConsentGiven?: (state: ConsentState) => void

Callback executado quando usuário dá consentimento pela primeira vez. Útil para inicializar analytics, registrar evento, etc.

Example

onConsentGiven={(state) => {
  console.log('Consentimento registrado:', state)
  // Inicializar Google Analytics, etc.
}}

`Optional`onConsentInit

onConsentInit?: (state: ConsentState) => void

Callback disparado após hidratação inicial (consentimento existente ou não).

`Optional`onConsentVersionChange

onConsentVersionChange?: (context: ConsentVersionChangeContext) => void

Callback disparado quando a chave de armazenamento muda (ex.: bump de versão). Recebe a chave anterior, a nova chave e um helper resetConsent.

Since

0.5.2

Example

<ConsentProvider
  storage={{ namespace: 'portal.gov.br', version: '2025-Q4' }}
  onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
    console.info('[consent] versão alterada', { previousKey, nextKey })
    analytics.clearUserStorage()
    resetConsent()
  }}
>
  <App />
</ConsentProvider>

`Optional`onPreferencesSaved

onPreferencesSaved?: (prefs: ConsentPreferences) => void

Callback executado quando usuário modifica preferências. Executado após salvar as mudanças.

Example

onPreferencesSaved={(prefs) => {
  console.log('Novas preferências:', prefs)
  // Reconfigurar scripts baseado nas preferências
}}

`Optional`PreferencesModalComponent

PreferencesModalComponent?: ComponentType<CustomPreferencesModalProps>

Componente customizado para substituir o modal padrão de preferências. Deve implementar a lógica de consentimento usando as props definidas em CustomPreferencesModalProps.

`Optional`preferencesModalProps

preferencesModalProps?: Record<string, unknown>

Props adicionais passadas para o modal customizado (repassadas sem transformação).

`Optional`storage

storage?: ConsentStorageConfig

Configuração da chave de armazenamento (cookie/localStorage) do consentimento. Permite definir namespace, versão e domínio compartilhado.

Since

0.5.2

`Optional`texts

texts?: Partial<AdvancedConsentTexts>

Textos customizados da interface (banner e modal). Todos os campos são opcionais - valores não fornecidos usam o padrão em português.

Example: Textos básicos:

texts={{
  bannerMessage: 'We use cookies...',
  acceptAll: 'Accept All',
  declineAll: 'Reject'
}}

Example: Textos ANPD para compliance:

texts={{
  controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
  dataTypes: 'Coletamos: endereço IP, preferências de navegação',
  userRights: 'Você pode solicitar acesso, correção ou exclusão dos seus dados'
}}

`Optional`textVariant

textVariant?: "formal" | "casual" | "concise" | "detailed"

Variação de tom aplicada aos textos (opcional). Utiliza texts.variants[variant] como override dos textos principais.

`Optional`theme

theme?: Theme

Tema Material-UI a ser aplicado ao redor dos componentes padrão.

Remarks

O tema é aplicado apenas nesta camada de apresentação via ThemeProvider. O core permanece agnóstico de UI.

Se você já tem um ThemeProvider no seu app, os componentes herdarão automaticamente. Esta prop é opcional e útil quando você quer um tema específico apenas para os componentes de consentimento.

Default Value

undefined (herda tema do contexto pai)

Since

0.5.0

Example

import { createTheme } from '@mui/material/styles'

const consentTheme = createTheme({
  palette: {
    primary: { main: '#2e7d32' },
    background: { paper: '#fafafa' }
  },
  typography: {
    fontFamily: 'Inter, sans-serif'
  }
})

<ConsentProvider
  theme={consentTheme}
  categories={{ enabledCategories: ['analytics'] }}
>
  <App />
</ConsentProvider>

Interface ConsentProviderProps

Remarks

Diferenças do Core

Quando Usar Este Provider

Quando Usar o Core

Category

Since

Example: Uso básico com defaults

Example: Com tema customizado

Example: Desabilitando componentes padrão

Hierarchy (View Summary)

Index

Properties

Properties

Optionalblocking

OptionalblockingMode

Remarks

OptionalblockingStrategy

Optionalcategories

Example: Apenas analytics:

Example: Com categoria padrão apenas:

children

Optionalcookie

Example

OptionalCookieBannerComponent

OptionalcookieBannerProps

OptionaldesignTokens

Example

OptionaldisableDefaultBanner

Remarks

Default Value

Since

Example

OptionaldisableDefaultFloatingButton

Remarks

Default Value

Since

Example

OptionaldisableDefaultModal

Remarks

Default Value

Since

Example

OptionaldisableDeveloperGuidance

OptionaldisableDiscoveryLog

Since

OptionaldisableFloatingPreferencesButton

OptionalFloatingPreferencesButtonComponent

OptionalfloatingPreferencesButtonProps

OptionalguidanceConfig

Since

Example

OptionalhideBranding

OptionalinitialState

Example

Optionallanguage

Default Value

OptionalonAuditLog

Since

Example

OptionalonConsentChange

OptionalonConsentGiven

Example

OptionalonConsentInit

OptionalonConsentVersionChange

Since

Example

OptionalonPreferencesSaved

Example

OptionalPreferencesModalComponent

OptionalpreferencesModalProps

Optionalstorage

Since

Optionaltexts

Example: Textos básicos:

Example: Textos ANPD para compliance:

OptionaltextVariant

Optionaltheme

Remarks

Default Value

`Optional`blocking

`Optional`blockingMode

`Optional`blockingStrategy

`Optional`categories

`Optional`cookie

`Optional`CookieBannerComponent

`Optional`cookieBannerProps

`Optional`designTokens

`Optional`disableDefaultBanner

`Optional`disableDefaultFloatingButton

`Optional`disableDefaultModal

`Optional`disableDeveloperGuidance

`Optional`disableDiscoveryLog

`Optional`disableFloatingPreferencesButton

`Optional`FloatingPreferencesButtonComponent

`Optional`floatingPreferencesButtonProps

`Optional`guidanceConfig

`Optional`hideBranding

`Optional`initialState

`Optional`language

`Optional`onAuditLog

`Optional`onConsentChange

`Optional`onConsentGiven

`Optional`onConsentInit

`Optional`onConsentVersionChange

`Optional`onPreferencesSaved

`Optional`PreferencesModalComponent

`Optional`preferencesModalProps

`Optional`storage

`Optional`texts

`Optional`textVariant

`Optional`theme