Configurando um template personalizado no Upcart

⚠️ Aviso importante

Templates personalizados exigem conhecimento técnico avançado de HTML, CSS, JavaScript e React. Certifique-se de ter experiência de desenvolvimento suficiente ou acesso a um desenvolvedor Shopify qualificado antes de continuar. Nossa equipe de suporte não fornecerá assistência com desenvolvimento, depuração ou solução de problemas de templates personalizados. Questões técnicas devem ser direcionadas a um Shopify expert ou desenvolvedor qualificado.

Recursos do editor de código

O editor de código de templates personalizados inclui ferramentas integradas para ajudar você a escrever templates válidos com mais facilidade.

IntelliSense de TypeScript

O editor entende TypeScript, então você recebe sugestões de autocomplete, verificação de tipos e documentação inline para todas as props disponíveis enquanto digita. As dicas de tipo das props são IntelliSense exclusivo do editor para ajudar você a escrever templates — elas não são algo que você escreve no template e nunca são executadas na sua loja.

Corpo do template editável

O editor expõe apenas o corpo JSX editável do seu template — não há linhas bloqueadas. O wrapper de função ao redor é adicionado automaticamente no momento do build e nunca é exibido no editor. Use Reset to default a qualquer momento para restaurar o template original caso suas edições quebrem a estrutura do template.

Seção General

O módulo Header permite personalizar o cabeçalho do carrinho com seu próprio design, mantendo funcionalidades essenciais do carrinho, como exibir a contagem de itens e fornecer um botão de fechar.

Props disponíveis - Template completo

Cabeçalho do cart drawer mostrando o título Cart, a contagem de itens e o botão de fechar

cartQuantity

Tipo: string
Descrição: O número atual de itens no carrinho, formatado como string
Uso: Exiba a contagem de itens do carrinho no seu design de cabeçalho personalizado

<h2>Shopping Cart ({props.cartQuantity})</h2>

closeHandler

Tipo: () => void
Descrição: Uma função de callback que fecha o carrinho quando acionada
Uso: Anexe a botões, ícones ou outros elementos interativos para fechar o carrinho

<button  
  onClick={props.closeHandler}  
  aria-label="Close cart"  
>×</button>

titleComponent

Tipo: React.ReactElement | null
Descrição: Um componente de título pré-renderizado para o cabeçalho do carrinho que inclui a estilização e as traduções adequadas
Uso: Exiba o título do carrinho com base na configuração das suas definições de carrinho

<div>{props.titleComponent}</div>

Seção Body

Announcements

O módulo Announcements permite personalizar a exibição de anúncios com seu próprio design, mantendo funcionalidades essenciais de anúncio, como controles de cronômetro e visibilidade condicional.

Props disponíveis - Template completo

Barra de anúncio do carrinho com um cronômetro de contagem regressiva reservando os produtos do cliente

announcementTemplate

Tipo: string
Descrição: O conteúdo HTML da mensagem do anúncio
Uso: Exiba a mensagem do anúncio nas suas implementações personalizadas

<div dangerouslySetInnerHTML={{ __html: props.announcementTemplate }} />

timer

Tipo: string
Descrição: O valor atual do cronômetro formatado como string
Uso: Exiba o cronômetro de contagem regressiva em implementações de anúncio personalizadas

<div>Time remaining: {props.timer}</div>

shouldUseTimer

Tipo: boolean
Descrição: Indica se a funcionalidade de cronômetro está habilitada para este anúncio
Uso: Renderize condicionalmente conteúdo e controles relacionados ao cronômetro

<div>  
  {props.shouldUseTimer && (  
    <span>{props.timer}</span>   
  )}  
</div>

isTimerExpiredAndShouldHide

Tipo: boolean
Descrição: Indica se o cronômetro expirou e o anúncio deve ser ocultado
Uso: Controle a visibilidade de todo o anúncio com base no estado do cronômetro

<div>  
  {!props.isTimerExpiredAndShouldHide && (  
    <div>{props.timer}</div>  
  )}  
</div>

Tiered Rewards

O módulo Rewards permite personalizar a exibição do progresso de recompensas com seu próprio design, mantendo funcionalidades essenciais de recompensas, como acompanhamento de marcos, visualização de progresso e mensagens de recompensa.

Props disponíveis - Template completo

Barra de progresso de recompensas em níveis com ícones de marcos de frete grátis e produto

rewardsMessageHtml

Tipo: string
Descrição: O conteúdo HTML da mensagem de recompensas
Uso: Exiba a mensagem de recompensas com formatação rica em implementações personalizadas

<div dangerouslySetInnerHTML={{ __html: props.rewardsMessageHtml }} />

milestonesCompleted

Tipo: number
Descrição: O número de marcos que foram concluídos
Uso: Exiba a contagem de conclusão ou calcule a porcentagem de conclusão

<div>  
  {Math.round((props.milestonesCompleted / props.milestonesData.milestonesToRender.length) * 100)}% Complete  
</div>

milestonesData

Tipo:

{  
  milestonesToRender: {  
    id: string;  
    label: string;  
    icon: React.ReactElement;  
    isCompleted: boolean;  
    positionPercent: number;  
  }[];  
  progressPercent: number;  
  showMilestones: boolean;  
  settings: {  
    iconContainerSize: string;  
    iconAlignment: string;  
    labelAlignment: string;  
    hideLabel: boolean;  
  };  
}

Descrição: Configuração completa de marcos e dados de progresso para o sistema de recompensas
Uso: Acesse informações de marcos, porcentagem de progresso e configurações de exibição
Propriedades:
- milestonesToRender: Array de objetos de marco com status de conclusão e posicionamento
- progressPercent: Progresso atual como porcentagem (0-100)
- showMilestones: Se os marcadores de marco devem ser exibidos
- settings: Configuração visual para a exibição de marcos

Discounts

O módulo Discounts oferece suporte a templates personalizados para que você possa criar sua própria exibição, mantendo funcionalidades essenciais como gerenciamento de regras, visibilidade de seções e apresentação de recompensas. O identificador interno de tipo de módulo para templates personalizados é TRIGGERED_REWARDS, para compatibilidade retroativa com código de template personalizado existente.

Props disponíveis - Template completo

rules

Tipo:

{  
  id: string;  
  title: string;  
  description: string;  
  conditionsMet: boolean;  
}[]

Descrição: Array de regras de Discount atualmente habilitadas
Uso: Exiba as recompensas disponíveis, seus títulos, descrições e se as condições de cada regra foram atendidas
Propriedades:
- id: Identificador único da regra de recompensa
- title: Título da regra de Discount
- description: Descrição da regra de recompensa
- conditionsMet: Se as condições da regra estão atualmente satisfeitas pelo carrinho. Use isso para construir padrões de UX como “você desbloqueou X” versus “gaste mais $Y para desbloquear X”

<div>
  {props.rules.map((rule) => (
    <div key={rule.id}>
      <h3>{rule.title}</h3>
      <p>{rule.conditionsMet ? "Reward unlocked!" : rule.description}</p>
    </div>
  ))}
</div>

showSection

Tipo: boolean
Descrição: Indica se a seção Discounts deve ser exibida
Uso: Controle a visibilidade de todo o módulo Discounts

<div>  
  {props.showSection && (  
    <div>  
      <h2>Available Rewards...</h2>  
    </div>  
  )}  
</div>

onToggleSection

Tipo: () => void
Descrição: Uma função de callback que alterna o estado de visibilidade da seção Discounts
Uso: Anexe a botões ou elementos interativos para permitir que os usuários mostrem/ocultem a seção de recompensas

<button type="button" onClick={props.onToggleSection}>  
  {props.showSection ? "Hide Rewards" : "Show Available Rewards"}  
</button>

Recommendations

O módulo Recommendation permite personalizar a exibição de produtos de upsell com seu próprio design, mantendo funcionalidades essenciais de e-commerce, como seleção de variantes, ações de adicionar ao carrinho e exibição de informações do produto.

Props disponíveis - Template de tile de recomendação

Tile de recomendação mostrando um produto de snowboard com preço e botão Add

O template de tile de recomendação compartilha a mesma interface de props do template de tile de upsell do módulo Upsells. Todas as props disponíveis, tipos e exemplos de uso estão documentados na seção do módulo Upsells abaixo.

Cart Items

O módulo Cart Items permite personalizar a exibição dos itens do carrinho com seu próprio design, mantendo funcionalidades essenciais de e-commerce. Este módulo oferece vários tipos de template, cada um com suas próprias props específicas para diferentes aspectos da exibição de itens do carrinho.

Exibindo um indicador de carregamento durante a adição ao carrinho ou atualizações do carrinho: O módulo Cart Items padrão não expõe um spinner de “adicionando ao carrinho” integrado. Se você quiser exibir um estado de carregamento enquanto um item está sendo adicionado ou uma operação de carrinho está em andamento, use o template Product tile e leia as props isLoading e loadingOperation (documentadas abaixo) para renderizar condicionalmente um spinner ou overlay. Templates personalizados exigem experiência de desenvolvimento — veja o aviso no topo desta página.

Props disponíveis - Template Product tile

Nota: Habilitar o template Product Tile sobrescreverá todos os outros templates deste módulo, incluindo Variant template, Properties template, Bundle template e Price template.
Se você quiser usar código personalizado em qualquer um desses templates, deve desativar o template Product Tile.

Tile de produto do carrinho com imagem, variante, preço promocional, seletor de quantidade e botão de assinatura

title

Tipo: string
Descrição: O título/nome do produto
Uso: Exiba o nome principal do produto nos itens do carrinho

variant

Tipo: React.ReactNode
Descrição: Componente de informações de variante pré-renderizado
Uso: Exiba detalhes da variante como componente React

properties

Tipo: React.ReactNode
Descrição: Componente de propriedades do produto pré-renderizado
Uso: Exiba propriedades do produto e informações de assinatura como componente React

bundle

Tipo: React.ReactNode
Descrição: Componente de detalhes do bundle pré-renderizado
Uso: Exiba informações do bundle como componente React

compareAtPrice

Tipo: string | undefined
Descrição: Preço de comparação formatado (preço original)
Uso: Exiba o preço original para itens em promoção

price

Tipo: string
Descrição: Preço atual formatado
Uso: Exiba o preço atual do item

savings

Tipo: string | undefined
Descrição: Valor de economia formatado
Uso: Exiba quanto o cliente está economizando

imageUrl

Tipo: string | undefined
Descrição: URL da imagem do produto
Uso: Exiba a imagem do produto

productUrl

Tipo: string | undefined
Descrição: URL da página do produto
Uso: Link para a página de detalhes do produto

quantity

Tipo: number
Descrição: Quantidade atual do item no carrinho
Uso: Exiba e gerencie a quantidade do item

showQuantitySelector

Tipo: boolean
Descrição: Se os controles de quantidade devem ser exibidos
Uso: Exiba condicionalmente o seletor de quantidade

discountCodes

Tipo: string[] | undefined
Descrição: Array de códigos de desconto aplicados a este item
Uso: Exiba descontos específicos do item

subscription

Tipo:

{  
  subscriptionUpgradeData: {  
    buttonText: string;  
    defaultSellingPlanId: number;  
  } | null;  
  sellingPlansData: {  
    sellingPlanGroups: {  
      name: string;  
      selling_plans: {  
        id: number;  
        name: string;  
      }[];  
    }[] | null;  
    activeSellingPlanId: string;  
    oneTimePurchaseText: string | null;  
  } | null;  
  upgradeSellingPlan: (item: CartItem, sellingPlanId: number) => void;  
  changeSellingPlan: (item: CartItem, value: string) => void;  
  getSellingPlanGroupText: (groupName: string, planName: string) => string;  
}

Descrição: Objeto completo de gerenciamento de assinatura com dados de upgrade, planos de venda e funções manipuladoras
Uso: Gerencie a funcionalidade de assinatura
O objeto subscription contém:
- subscriptionUpgradeData: Informações de upgrade (null se nenhum upgrade estiver disponível)
  - buttonText: Texto do botão de upgrade
  - defaultSellingPlanId: ID do plano de venda padrão para upgrades
- sellingPlansData: Opções de planos de venda disponíveis (null se não houver planos)
  - sellingPlanGroups: Array de grupos de planos com seus planos de venda
  - activeSellingPlanId: ID do plano de venda atualmente selecionado
  - oneTimePurchaseText: Texto da opção de compra única (null se não disponível)
- upgradeSellingPlan: Função para fazer upgrade para um plano de venda específico
- changeSellingPlan: Função para alterar o plano de venda atual
- getSellingPlanGroupText: Função utilitária para formatar o texto de exibição do plano de venda

onIncrease

Tipo: () => void
Descrição: Função para aumentar a quantidade do item
Uso: Trate ações de aumento de quantidade

onDecrease

Tipo: () => void
Descrição: Função para diminuir a quantidade do item
Uso: Trate ações de diminuição de quantidade

onDeleteProduct

Tipo: () => void
Descrição: Função para remover o item do carrinho
Uso: Trate a remoção de itens

onQuantityChange

Tipo: (quantity: string) => void
Descrição: Função para tratar a entrada direta de quantidade
Uso: Trate alterações manuais de quantidade

handleInputChange

Tipo: (e: React.ChangeEvent<HTMLInputElement>) => void
Descrição: Manipulador de alteração de entrada para o campo de quantidade
Uso: Trate alterações no campo de entrada de quantidade

replaceItemWithVariant

Tipo: (variantId: string) => Promise<{ success: boolean }>
Descrição: Função para substituir o item por uma variante diferente
Uso: Trate a troca de variantes

isLoading

Tipo: boolean
Descrição: Estado de carregamento para operações do carrinho
Uso: Exiba indicadores de carregamento

loadingOperation

Tipo: 'increase' | 'decrease' | 'inputChange' | 'remove' | 'subscription' | undefined
Descrição: Operação específica em carregamento no momento
Uso: Exiba estados de carregamento específicos por operação

setLoadingOperation

Tipo: (op: "increase" | "decrease" | "inputChange" | "remove" | "subscription" | undefined) => void
Descrição: Função para definir o estado da operação de carregamento
Uso: Gerencie estados de carregamento para diferentes operações

rawItem

Tipo: CartItem (Consulte o tipo CartItem abaixo)
Descrição: Dados brutos do item do carrinho contendo todas as informações

Props disponíveis - Template Variant

item

Tipo: CartItem (Consulte o tipo CartItem abaixo)
Descrição: Dados brutos do item do carrinho contendo informações da variante
Uso: Acesse detalhes da variante a partir do item do carrinho

Props disponíveis - Template Properties

Linha de propriedade do item do carrinho mostrando uma nota de mensagem de presente

productProperties

Tipo: { key: string; value: string; isUrl?: boolean; }[]
Descrição: Array de propriedades do produto (campos personalizados, propriedades de item de linha)

subscriptionLabel

Tipo: string | undefined
Descrição: Rótulo para informações de assinatura

Props disponíveis - Template Bundle

Bundle expandido listando três produtos componentes incluídos com variantes

getSizedImageUrl

Tipo: getSizedImageUrl: ({ src, width, height }: SizedImageParams) => string
Descrição: Função utilitária para obter URLs de imagem com o tamanho adequado

item

Tipo:

{  
  itemComponents: {  
    quantity: number;  
    image: {  
      url: string;  
      height: number | null;  
      width: number | null;  
      alt: string;  
    };  
    product: {  
      title: string;  
      has_only_default_variant: boolean;  
    };  
    variantTitle: string;  
  }[];  
  variantTitle: string | undefined;  
  hasComponents: boolean;  
}

Descrição: Informações do item de bundle incluindo componentes. itemComponents é um array de objetos de componente — faça um map sobre ele para renderizar cada componente do bundle.

showDetailsText

Tipo: string | undefined
Descrição: Texto da ação “mostrar detalhes”
Uso: Exiba o texto do botão de expandir

hideDetailsText

Tipo: string | undefined
Descrição: Texto da ação “ocultar detalhes”

isExpanded

Tipo: boolean
Descrição: Se os detalhes do bundle estão expandidos

toggleCollapsible

Tipo: () => void
Descrição: Função para alternar a visibilidade dos detalhes do bundle
Uso: Trate ações de expandir/recolher

chevronDownIconComponent

Tipo: React.ReactElement
Descrição: Ícone de seta pré-renderizado para expandir/recolher
Uso: Exiba um indicador de expandir/recolher consistente

Props disponíveis - Template Price

Preço do carrinho mostrando o preço original riscado com o preço promocional e a economia

compareAtPrice

Tipo: string | undefined
Descrição: Preço de comparação formatado (preço original)
Uso: Exiba o preço original para itens em promoção

price

Tipo: string
Descrição: Preço atual formatado
Uso: Exiba o preço atual do item

savings

Tipo: string | undefined
Descrição: Valor de economia formatado
Uso: Exiba quanto o cliente está economizando

Propriedades do objeto CartItem

O objeto CartItem contém todas as informações detalhadas sobre um item de linha do carrinho. Este objeto está disponível como props.rawItem no template Product Tile e props.item no template Variant.

Identificação principal

key (string) - Identificador único deste item do carrinho.
id (number) - ID da variante (campo legado, use variant_id em vez dele)
variant_id (number) - O ID da variante do Shopify para este item
product_id (number) - O ID do produto do Shopify
lineIdxFrom1 (number) - Índice baseado em 1 deste item no carrinho original antes das modificações

Informações do produto

title (string) - O título do item de linha (normalmente o título da variante)
product_title (string) - O título principal do produto
handle (string) - Handle da URL do produto (por exemplo, “camp-stool”)
vendor (string) - Nome do fornecedor/marca do produto
product_type (string) - Categoria/tipo do produto para fins fiscais
sku (string) - Identificador de Stock Keeping Unit
product_description (string) - Descrição completa do produto
product_has_only_default_variant (boolean) - Se o produto tem apenas uma variante

Preços (todos os preços em centavos)

quantity (number) - Número deste item no carrinho
price (number) - Preço unitário antes dos descontos
original_price (number) - Igual a price
discounted_price (number) - Preço unitário após descontos no nível do produto
compare_at_price (number | null) - Preço de comparação (MSRP). Nota: este campo é adicionado pelo Upcart, não é fornecido pela API de carrinho do Shopify
final_line_price (number) - Preço total após descontos no nível do produto (quantity × discounted_price)
original_line_price (number) - Preço total antes dos descontos (quantity × price)
line_price (number) - Preço total após todos os descontos
final_price (number) - Obsoleto - Preço unitário após descontos de produto (não considera a quantidade)
total_discount (number) - Igual a line_level_total_discount
line_level_total_discount (number) - Valor total de desconto aplicado a este item de linha

Mídia e URLs

image (string) - URL da imagem principal do produto
url (string) - Caminho de URL relativo para a página do produto (por exemplo, “/products/camp-stool?variant=42789611372803”)
featured_image (object | null) - Detalhes da imagem em destaque:
- alt (string) - Texto alternativo da imagem
- aspect_ratio (number) - Proporção da imagem
- height (number) - Altura da imagem em pixels
- url (string) - URL da imagem
- width (number) - Largura da imagem em pixels

Variantes e opções

variant_title (string | null) - Título da variante (por exemplo, “Large / Red”)
variant_options (string[]) - Array de valores das opções da variante
options_with_values (Array) - Informações detalhadas das opções:
- name (string) - Nome da opção (por exemplo, “Size”)
- value (string) - Valor da opção (por exemplo, “Large”)
untranslated_product_title (string | undefined) - Título original do produto antes da tradução (apenas em respostas de mutação do carrinho)
untranslated_variant_title (string | undefined) - Título original da variante antes da tradução (apenas em respostas de mutação do carrinho)

Propriedades personalizadas e metadados

properties (Record<string, any> | null) - Propriedades personalizadas do item de linha, ou null quando a linha não tem nenhuma — verifique antes de ler uma chave. Propriedades cujas chaves começam com __ ficam sempre ocultas dos clientes; chaves que começam com um único _ também ficam ocultas quando a configuração de carrinho Hide properties starting with single underscore ”_” está ativada.
gift_card (boolean) - Se este item é um cartão-presente
taxable (boolean) - Se este item está sujeito a impostos
requires_shipping (boolean) - Se este item exige envio
grams (number) - Peso do item em gramas

Descontos e promoções

discounts (Array) - Informações simplificadas de desconto:
- amount (number) - Valor do desconto em centavos
- title (string) - Título/nome do desconto
line_level_discount_allocations (Array) - Informações detalhadas de alocação de desconto:
- amount (number) - Valor do desconto em centavos
- discount_application (object) - Detalhes completos da aplicação do desconto:
  - allocation_method (string) - Como o desconto é alocado
  - created_at (string) - Quando o desconto foi criado
  - description (string | null) - Descrição do desconto
  - key (string) - Identificador de chave do desconto
  - target_selection (string) - O que o desconto atinge
  - target_type (string) - Tipo de alvo
  - title (string) - Título do desconto
  - total_allocated_amount (number) - Valor total alocado
  - type ('discount_code' | '') - Tipo de desconto (string vazia para descontos automáticos)
  - value (string) - Valor do desconto
  - value_type (string) - Como o valor é aplicado

Produtos em bundle

has_components (boolean | undefined) - Se este item é um bundle contendo outros produtos (apenas em respostas GET do carrinho)
item_components (Array | null | undefined) - Detalhes dos componentes do bundle:
- quantity (number) - Quantidade deste componente
- image (object) - Imagem do componente:
  - url (string) - URL da imagem
  - height (number | null) - Altura da imagem
  - width (number | null) - Largura da imagem
  - alt (string) - Texto alternativo
product (object) - Informações do produto componente:
- title (string) - Título do produto
- has_only_default_variant (boolean) - Se o produto tem apenas a variante padrão
variantTitle (string) - Título da variante do componente

Regras de negócio

quantity_rule (object | undefined) - Restrições de quantidade (apenas em respostas GET do carrinho):
- min (number) - Quantidade mínima permitida
- max (number | null) - Quantidade máxima permitida (null = sem limite)
- increment (number) - Incremento de quantidade

Informações de assinatura

selling_plan_allocation (object | undefined) - Detalhes de assinatura/plano de venda:
- price (number) - Preço da assinatura em centavos
- compare_at_price (number | null) - Preço de comparação da assinatura
- per_delivery_price (number) - Preço por entrega
- selling_plan (object) - Detalhes do plano de venda:
  - id (number) - ID do plano de venda
  - name (string) - Nome do plano
  - description (string) - Descrição do plano
  - options (Array) - Opções do plano:
    - name (string) - Nome da opção
    - position (number) - Posição da opção
    - value (string) - Valor da opção
  - recurring_deliveries (boolean) - Se o plano tem entregas recorrentes

Metadados de integração

__appIntegrated (object | undefined) - Dados de integração de apps de terceiros:
- app ('stay.ai') - Identificador do app integrado
- bundleRole ('parent' | 'child') - Papel na estrutura do bundle

Upsells

O módulo Upsells permite personalizar a exibição de produtos de upsell com seu próprio design, mantendo funcionalidades essenciais de e-commerce, como seleção de variantes, ações de adicionar ao carrinho e exibição de informações do produto.

Props disponíveis - Template de tile de upsell

Tile de upsell mostrando um produto com preço promocional, menu suspenso de variantes e botão Add

itemUrl

Tipo: string
Descrição: A URL da página do produto
Uso: Crie links para a página de detalhes do produto para melhorar a navegação do usuário

<a href={props.itemUrl} className="product-link">  
  <img src={props.imageUrl} alt={props.altText} />  
</a>

imageUrl

Tipo: string | undefined
Descrição: A URL da imagem do produto
Uso: Exiba imagens de produto em implementações de upsell personalizadas
Fallback: Trate valores undefined com elegância usando imagens de placeholder

description

Tipo: string
Descrição: A descrição do produto
Uso: Exiba a descrição do produto em implementações de upsell personalizadas

altText

Tipo: string
Descrição: Texto alternativo da imagem do produto para acessibilidade
Uso: Forneça suporte a leitores de tela e melhore a conformidade com acessibilidade

<img   
  src={props.imageUrl}   
  alt={props.altText}  
  className="product-image"  
/>

productId

Tipo: string
Descrição: O identificador único do produto
Uso: Rastreie produtos, implemente análises ou use na funcionalidade de adicionar ao carrinho

productTitle

Tipo: string
Descrição: O título/nome do produto
Uso: Exiba o nome do produto em implementações de upsell personalizadas

<div>  
  <h3>{props.productTitle}</h3>  
</div>

oldPrice e newPrice

Tipo: string | null (oldPrice), string (newPrice)
Descrição: Preço de comparação e preço atual formatados
Uso: Exiba informações de preço com indicadores de promoção

isSingleVariant

Tipo: boolean
Descrição: Indica se o produto tem apenas uma variante
Uso: Renderize condicionalmente elementos de UI de seleção de variante

productOptions

Tipo: { name: string; position: 1 | 2 | 3; values: string[]; }[]
Descrição: Configuração completa das opções do produto, incluindo todas as escolhas disponíveis
Uso: Acesse informações detalhadas das opções do produto para uma UI avançada de seleção de variantes

variantOptions

Tipo: { label: string; value: string }[]
Descrição: Opções de variante disponíveis para o produto
Uso: Crie menus suspensos ou botões de seleção de variante
Estrutura: Cada opção contém um rótulo de exibição e um identificador de valor único

selectedVariantId e selectedVariantLabel

Tipo: string (selectedVariantId), string | undefined (selectedVariantLabel)
Descrição: ID da variante atualmente selecionada e seu rótulo de exibição
Uso: Rastreie e exiba as informações da variante selecionada

onVariantChange

Tipo: (variantId: string) => void
Descrição: Função para tratar mudanças na seleção de variante
Uso: Atualize a variante selecionada quando o usuário fizer uma seleção

onAddClick

Tipo: (productId: string, variantId?: string) => void
Descrição: Função para tratar a adição do produto ao carrinho
Uso: Implemente a funcionalidade de adicionar ao carrinho com a identificação adequada de produto e variante

<button   
  onClick={() => props.onAddClick(props.productId, props.selectedVariantId)}  
  disabled={props.addLoading}  
>  
  {props.addLoading ? 'Adding...' : props.addButtonText}  
</button>

rating e reviewCount

Tipo: number | undefined (rating), string | undefined (reviewCount)
Descrição: Classificação do produto e texto formatado da contagem de avaliações
Uso: Exiba prova social e indicadores de qualidade do produto

addLoading e addButtonText

Tipo: boolean (addLoading), string (addButtonText)
Descrição: Estado de carregamento da ação de adicionar ao carrinho e texto do botão
Uso: Forneça feedback ao usuário durante operações do carrinho e personalize o texto do botão

cartItemsCount

Tipo: number
Descrição: O número atual de itens no carrinho
Uso: Exiba o status do carrinho ou implemente lógica baseada no carrinho

Additional Notes

O módulo Notes permite personalizar a funcionalidade de notas do carrinho com seu próprio design, mantendo capacidades essenciais de anotação, como seções expansíveis, tratamento de entrada de texto e estados de carregamento.

Props disponíveis - Template completo

Seção de notas do carrinho com um campo de texto expansível de instruções especiais

cartNote

Tipo: string
Descrição: O conteúdo atual da nota do carrinho inserido pelo cliente
Uso: Exiba e gerencie o texto da nota do carrinho em implementações personalizadas

<textarea  
  value={props.cartNote}  
  ...  
/>

notesPlaceholder

Tipo: string
Descrição: Texto de placeholder para o campo de entrada de notas
Uso: Ofereça orientação aos clientes sobre o que incluir nas suas notas

<textarea  
  placeholder={props.notesPlaceholder}  
  ...  
/>

notesTitle

Tipo: string
Descrição: O texto do título/cabeçalho da seção de notas
Uso: Exiba o título da seção em implementações de notas personalizadas

<h3 className="notes-title" dangerouslySetInnerHTML={{ __html: props.notesTitle }} />

chevronDownIconComponent

Tipo: React.ReactElement
Descrição: Componente de ícone de seta pré-renderizado para a funcionalidade de expandir/recolher
Uso: Exiba indicadores de expandir/recolher consistentes em implementações personalizadas

loadingIndicatorComponent

Tipo: React.ReactElement | null
Descrição: Componente de indicador de carregamento pré-renderizado para operações assíncronas
Uso: Exiba estados de carregamento durante operações de salvamento de nota

handleCartNoteChange

Tipo: (newCartNote: string) => void
Descrição: Função para tratar alterações no conteúdo da nota do carrinho
Uso: Atualize a nota do carrinho quando o usuário modificar o texto

isExpanded

Tipo: boolean
Descrição: Indica se a seção de notas está atualmente expandida
Uso: Controle a visibilidade da área de entrada de notas

toggleCollapsible

Tipo: () => void
Descrição: Função para alternar o estado expandido/recolhido da seção de notas
Uso: Anexe a botões ou elementos interativos para controlar a visibilidade da seção

Add-ons

O módulo Addons permite personalizar a exibição de produtos complementares com seu próprio design, mantendo funcionalidades essenciais de e-commerce, como exibição de informações do produto, preços, controles de alternância e formatação de moeda.

Props disponíveis - Template completo

Linha de produto complementar mostrando um cartão-presente com preço e botão de habilitar

addonProduct

Tipo:

{  
  product: {  
    id: number;  
    title: string;  
    description: string;  
  };  
  variant: {  
    id: number;  
    price: number;  
    compare_at_price: number | null;  
  };  
  image: {  
    src: string;  
    alt: string;  
  };  
}

Descrição: Informações completas do produto complementar, incluindo detalhes do produto, preço da variante e dados da imagem
Uso: Acesse todas as informações do produto necessárias para exibir produtos complementares
Estrutura: Contém objetos aninhados de produto, variante e imagem com dados abrangentes do produto
- Propriedades do objeto Product addonProduct.product
  - id: Identificador numérico único do produto
  - title: Nome de exibição do produto complementar
  - description: Conteúdo HTML da descrição do produto
- Propriedades do objeto Variant
  - id: Identificador numérico único da variante
  - price: Preço atual em centavos
  - compare_at_price: Preço original em centavos (null se não houver preço de comparação)
- Propriedades do objeto Image
  - src: URL da imagem do produto
  - alt: Texto alternativo da imagem (para acessibilidade)

toggle

Tipo:

{  
  state: 'enabled' | 'disabled' | 'loading';  
  handleEnable: () => void;  
  handleDisable: () => void;  
} | null

Descrição: Estado do controle de alternância e manipuladores para habilitar/desabilitar o complemento
Uso: Implemente a funcionalidade de alternância interativa para a seleção de complementos
Estados: Três estados possíveis - enabled, disabled e loading
Manipuladores: Funções separadas para as ações de habilitar e desabilitar

moneyFormat

Tipo: string
Descrição: A string de formato de moeda usada para a formatação de preços
Uso: Passe para a função formatMoney para uma exibição de moeda consistente

formatMoney

Tipo:

(options: {  
  cents: string | number;  
  format?: string;  
  shouldRemoveHTML?: boolean;  
}) => string

Descrição: Função utilitária para formatar valores monetários
Uso: Formate preços de forma consistente com as configurações de moeda da loja
Parâmetros: Recebe o valor em centavos, uma string de formato opcional e a opção de remoção de HTML

Discount Codes

O módulo Discount Code permite personalizar a funcionalidade de entrada de código de desconto com seu próprio design, mantendo capacidades essenciais de e-commerce, como validação de código, envio de formulário e feedback ao usuário.

Props disponíveis - Template completo

Campo de entrada de código de desconto com um botão Apply

indicator

Tipo: 'validating' | 'invalid' | 'none'
Descrição: Estado de validação atual da entrada do código de desconto
Uso: Exiba o feedback de UI apropriado com base no status de validação
Estados:
- validating: O código está sendo processado/validado
- invalid: A validação do código falhou
- none: Sem estado de validação (padrão/ocioso)

discountCodeInput

Tipo: string
Descrição: Valor atual do campo de entrada do código de desconto
Uso: Exiba e gerencie o texto do código de desconto inserido pelo usuário

<input  
  type="text"  
  value={props.discountCodeInput}  
  onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
  ...  
/>

discountCodePlaceholder

Tipo: string
Descrição: Texto de placeholder para o campo de entrada do código de desconto
Uso: Ofereça orientação aos usuários sobre o que inserir no campo

discountCodeButtonText

Tipo: string
Descrição: Texto a ser exibido no botão de aplicar/enviar
Uso: Personalize o texto do botão de envio do código de desconto

setDiscountCodeInput

Tipo: (value: string | ((prev: string) => string)) => void
Descrição: Função para atualizar o valor da entrada do código de desconto
Uso: Trate as alterações de entrada do usuário no campo de código de desconto

handleSubmit

Tipo: (e: React.FormEvent<HTMLFormElement>) => void
Descrição: Função para tratar o envio do formulário para a aplicação do código de desconto
Uso: Processe a validação e a aplicação do código de desconto
Evento: Trata eventos de envio de formulário

<form onSubmit={props.handleSubmit} >  
  <div className="input-group">  
    <input  
      type="text"  
      value={props.discountCodeInput}  
      onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
      placeholder={props.discountCodePlaceholder}  
    />   
    <button   
      type="submit"  
      disabled={props.indicator === 'validating' || !props.discountCodeInput.trim()}  
    >  
      {props.discountCodeButtonText}  
    </button>  
  </div>  
</form>

Cart Summary

O módulo Cart Summary permite personalizar o resumo do carrinho e a exibição de descontos com seu próprio design, mantendo funcionalidades essenciais de e-commerce, como gerenciamento de descontos, cálculo de economia e transparência de preços.

Props disponíveis - Template completo

Linha de desconto do resumo do carrinho mostrando um código de desconto aplicado e o valor

totalSavingsText

Tipo: string
Descrição: Rótulo de texto da seção de economia total
Uso: Exiba o rótulo de economia em implementações personalizadas de resumo do carrinho

discountApplications

Tipo:

{  
  key: string;  
  title: string;  
  type: 'discount_code' | '';  
}[]

Descrição: Array de códigos de desconto aplicados e descontos automáticos
Uso: Exiba todos os descontos ativos com seus títulos e tipos
Estrutura: Cada desconto contém uma chave única, um título de exibição e um identificador de tipo

cartTotalDiscount

Tipo: number
Descrição: O valor total do desconto em centavos
Uso: Acesse o valor bruto do desconto para cálculos ou formatação personalizada

showCartTotalDiscount

Tipo: boolean
Descrição: Indica se o desconto total deve ser exibido. Marcado como obsoleto em favor de showTotalSavings, mas veja a nota abaixo — dentro de um template personalizado, esta ainda é a prop disponível.
Uso: Renderize condicionalmente informações de desconto com base nas configurações

formattedCartTotalDiscount

Tipo: string
Descrição: String HTML pré-formatada do valor total do desconto. Marcada como obsoleta em favor de formattedTotalSavings, mas veja a nota abaixo.
Uso: Exiba o valor do desconto devidamente formatado com símbolos de moeda

showTotalSavings e formattedTotalSavings não estão disponíveis dentro de um template personalizado. Elas existem no contexto interno do módulo, mas o template do Cart summary recebe apenas showCartTotalDiscount e formattedCartTotalDiscount — ler o par mais novo retorna undefined. Use as duas acima e observe que elas mostram apenas o total de descontos; elas não seguem a configuração Show compare-at price savings in footer total.

isRemovingDiscount

Tipo: boolean
Descrição: Indica se uma operação de remoção de desconto está em andamento
Uso: Exiba estados de carregamento durante a remoção do desconto

handleRemoveDiscount

Tipo: () => Promise<void>
Descrição: Função para tratar a remoção do código de desconto
Uso: Remova códigos de desconto aplicados do carrinho

totalCompareAtPrice

Tipo: number
Descrição: Soma total dos preços de comparação (todos os itens do carrinho)
Uso: Calcule e exiba a economia ou informações de preço original

totalAfterAllDiscounts

Tipo: number
Descrição: Total final do carrinho em centavos após a aplicação de todos os descontos
Uso: Exiba o preço final que os clientes pagarão

originalTotalPrice

Tipo: number
Descrição: Total original do carrinho em centavos antes de qualquer desconto
Uso: Mostre o preço original para transparência e cálculo de economia

cartItemCount

Tipo: number
Descrição: Número total de itens no carrinho
Uso: Exiba informações de contagem de itens em resumos do carrinho

Trust Badges

O módulo Trust Badges permite personalizar a exibição de selos de confiança com seu próprio design, mantendo funcionalidades essenciais de construção de confiança, como visibilidade condicional dos selos e tratamento adequado de imagens.

Props disponíveis - Template completo

showBadge

Tipo: boolean
Descrição: Indica se o selo de confiança deve ser exibido
Uso: Controle a visibilidade dos selos de confiança com base nas configurações do módulo

badgeUrl

Tipo: string
Descrição: A URL da imagem do selo de confiança a ser exibida
Uso: URL de origem da imagem do selo de confiança em implementações personalizadas

​⚠️ Aviso importante

​Recursos do editor de código

​IntelliSense de TypeScript

​Corpo do template editável

​Seção General

​Header

​Props disponíveis - Template completo

​Seção Body

​Announcements

​Props disponíveis - Template completo

​Tiered Rewards

​Props disponíveis - Template completo

​Discounts

​Props disponíveis - Template completo

​Recommendations

​Props disponíveis - Template de tile de recomendação

​Cart Items

​Props disponíveis - Template Product tile

​Props disponíveis - Template Variant

​Props disponíveis - Template Properties

​Props disponíveis - Template Bundle

​Props disponíveis - Template Price

​Propriedades do objeto CartItem

​Identificação principal

​Informações do produto

​Preços (todos os preços em centavos)

​Mídia e URLs

​Variantes e opções

​Propriedades personalizadas e metadados

​Descontos e promoções

​Produtos em bundle

​Regras de negócio

​Informações de assinatura

​Metadados de integração

​Upsells

​Props disponíveis - Template de tile de upsell

​Additional Notes

​Props disponíveis - Template completo

​Seção Footer

​Add-ons

​Props disponíveis - Template completo

​Discount Codes

​Props disponíveis - Template completo

​Cart Summary

​Props disponíveis - Template completo

​Trust Badges

​Props disponíveis - Template completo

⚠️ Aviso importante

Recursos do editor de código

IntelliSense de TypeScript

Corpo do template editável

Seção General

Header

Props disponíveis - Template completo

Seção Body

Announcements

Props disponíveis - Template completo

Tiered Rewards

Props disponíveis - Template completo

Discounts

Props disponíveis - Template completo

Recommendations

Props disponíveis - Template de tile de recomendação

Cart Items

Props disponíveis - Template Product tile

Props disponíveis - Template Variant

Props disponíveis - Template Properties

Props disponíveis - Template Bundle

Props disponíveis - Template Price

Propriedades do objeto CartItem

Identificação principal

Informações do produto

Preços (todos os preços em centavos)

Mídia e URLs

Variantes e opções

Propriedades personalizadas e metadados

Descontos e promoções

Produtos em bundle

Regras de negócio

Informações de assinatura

Metadados de integração

Upsells

Props disponíveis - Template de tile de upsell

Additional Notes

Props disponíveis - Template completo

Seção Footer

Add-ons

Props disponíveis - Template completo

Discount Codes

Props disponíveis - Template completo

Cart Summary

Props disponíveis - Template completo

Trust Badges

Props disponíveis - Template completo