Interface ConsentProviderProps

Propriedades do componente ConsentProvider - configuração principal da biblioteca.

Since

0.1.0

Example: Uso básico (configuração mínima):

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

Example: Configuração completa com textos ANPD:

<ConsentProvider
  categories={{
    enabledCategories: ['analytics', 'functional'],
  }}
  texts={{
    bannerMessage: 'Utilizamos cookies conforme LGPD...',
    controllerInfo: 'Controlado por: Ministério XYZ - CNPJ: 00.000.000/0001-00',
    dataTypes: 'Coletamos: dados de navegação para análise estatística',
    userRights: 'Direitos: acessar, corrigir, excluir dados',
    contactInfo: 'DPO: dpo@ministerio.gov.br'
  }}
  onConsentGiven={(state) => console.log('Consentimento:', state)}
>
  <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;
    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";
}

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`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.

Interface ConsentProviderProps

Category

Since

Example: Uso básico (configuração mínima):

Example: Configuração completa com textos ANPD:

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

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

Settings

On This Page

`Optional`blocking

`Optional`blockingMode

`Optional`blockingStrategy

`Optional`categories

`Optional`cookie

`Optional`CookieBannerComponent

`Optional`cookieBannerProps

`Optional`designTokens

`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