Componente Navigation Menu para Angular | ng-hub-ui-nav
Componente de navegación para Angular con dropdowns, paneles drill-down, colapso responsive, integración con Router y theming mediante variables CSS.
Referencia API
Aquí tienes el contrato completo de nav: todo lo que puedes enlazar, escuchar, proyectar y personalizar, reunido en un solo sitio. Enlaza lo que necesites y dale el estilo que quieras — es standalone y reactivo con signals.
Inputs
Ajusta nav a tu gusto con 34 inputs. Se enlazan como cualquier @Input de Angular.
| Nombre | Tipo | Por defecto | Descripción |
|---|---|---|---|
itemsObligatorio | HubNavItem[] | — | Array de elementos de navegación a renderizar. Cada elemento define su tipo (link, dropdown, header, separator, custom), label, ruta, icono, badge, children y más. |
config | Partial<HubNavConfig> | {} | Anulaciones de configuración parciales que se combinan con los valores por defecto globales. Controla la orientación, el disparador del dropdown, el modo de colapso, el breakpoint, la posición y más. |
navClass | string | '' | Clase CSS adicional aplicada al elemento contenedor del nav. |
itemTemplate | TemplateRef<unknown> | null | null | Plantilla personalizada opcional para renderizar los elementos del nav mediante input binding. La directiva hubNavItemTemplate tiene prioridad sobre este input. |
autoOpenFromRoute | boolean | false | Cuando es true, el nav abre automáticamente los dropdowns y los paneles de drill-down que coinciden con la URL activa del router al inicializarse y tras cada navegación. Útil para navegaciones de tipo sidebar donde la URL gobierna el estado de apertura. |
color | 'primary' | 'success' | 'danger' | 'warning' | 'info' | string | undefined | Acento semántico aplicado a los indicadores de hover/activo. Acepta un nombre semántico (primary, success, danger, warning, info), un nombre de acento registrado, un color CSS con nombre o un literal #hex / rgb() / oklch() / var(). Los nombres sueltos se resuelven al token --hub-sys-color-<name>; por defecto es primary cuando se omite. |
rail | boolean (two-way: model) | false | Rail de iconos solo de escritorio. Con true, una navegación vertical se renderiza al ancho del rail mostrando solo iconos. Se ignora por debajo de collapseBreakpoint, donde siempre gana el comportamiento offcanvas. Enlazable bidireccionalmente con [(rail)]. |
orientation (config) | 'horizontal' | 'vertical' | 'horizontal' | Orientación de la navegación: horizontal renderiza una barra superior, vertical renderiza una barra lateral. |
verticalExpandMode (config) | 'accordion' | 'flyout' | 'panel' | 'accordion' | Cómo se expanden los elementos hijos en orientación vertical: accordion expande inline, flyout abre un submenú lateral posicionado, panel abre paneles de drill-down apilados. |
dropdownTrigger (config) | 'hover' | 'click' | 'both' | 'click' | Mecanismo que abre los menús dropdown: con hover, con click o ambos. |
dropdownRenderMode (config) | 'inline' | 'overlay' | 'inline' | Estrategia de renderizado para los menús dropdown y flyout: inline dentro del DOM del nav, u overlay en una capa a nivel de body para evitar recortes. El modo panel de drill-down no se ve afectado. |
position (config) | 'static' | 'sticky' | 'fixed' | 'static' | Estrategia de posicionamiento CSS para el contenedor del nav. El posicionamiento sticky solo se activa en la navegación vertical. |
stickyTop (config) | string | '0px' | Desplazamiento superior usado cuando el posicionamiento sticky está activado. Acepta cualquier valor de longitud CSS válido. |
collapseMode (config) | 'offcanvas' | 'dropdown' | 'fullscreen' | 'offcanvas' | Modo de visualización cuando el menú se colapsa en viewports pequeños: cajón deslizante offcanvas, dropdown bajo el toggler, u overlay fullscreen. |
collapseBreakpoint (config) | number | 992 | Ancho de viewport en píxeles por debajo del cual el menú se colapsa. Ponlo a 0 para desactivar el colapso responsive. |
offcanvasPosition (config) | 'start' | 'end' | 'top' | 'bottom' | 'start' | Lado desde el que se desliza el panel offcanvas. Solo se aplica cuando collapseMode es offcanvas. |
ariaLabel (config) | string | 'Navigation' | Etiqueta accesible aplicada al elemento nav. |
panelMaxVisible (config) | number | 3 | Número máximo de paneles visibles simultáneamente en el modo de expansión panel. Superado ese límite, el último panel profundiza en el sitio con navegación hacia atrás. |
sidebarSide (config) | 'left' | 'right' | 'left' | Lado físico de la barra lateral: left (los paneles se extienden hacia la derecha) o right (los paneles se extienden hacia la izquierda). |
panelWidth (config) | string | '16rem' | Ancho de cada panel de drill-down. Acepta cualquier valor de ancho CSS válido. |
railToggle (config) | boolean | true | Si el toggle integrado del borde se renderiza en la columna primaria de una navegación vertical de escritorio. Desactívalo cuando la aplicación aporte su propio toggle. Totalmente tematizable con los tokens --hub-nav-rail-toggle-*, incluida una flecha SVG reemplazable. |
followReplacedUrls (config) | boolean | number | true | Con cuánta avidez el menú sigue a un scroll spy, que informa de la posición del lector reemplazando la URL: true sigue cada informe, un número de milisegundos sigue solo cuando cesan, false no sigue nunca. |
activeIndicator (config) | boolean | false | Si la marca de activo viaja entre ítems en vez de aparecer y desaparecer en su sitio. Desactivado por defecto; respeta prefers-reduced-motion. |
labels (config) | Partial<HubNavLabels> | undefined | Sobrescrituras por instancia de las etiquetas accesibles integradas. Las omitidas se resuelven desde las claves compartidas HUBUI.NAV.* y después desde los valores ingleses por defecto. |
enabled (hubNavScrollSpy) — bound as [hubNavScrollSpy] | boolean | true | Activa o desactiva el seguimiento de secciones. Se enlaza a través del propio selector: [hubNavScrollSpy]="false" apaga el spy. |
offset (hubNavScrollSpy) | number | 120 | Desplazamiento superior en píxeles usado para compensar cabeceras sticky al calcular la sección activa. |
sectionSelector (hubNavScrollSpy) | string | '[data-hub-nav-scroll-spy-section]' | Selector CSS usado para localizar los elementos de sección rastreables dentro del contenedor anfitrión. |
sectionId (hubNavScrollSpySection) — bound as [hubNavScrollSpySection] | string | null | null | Id de sección opcional para una sección rastreada. Cuando se omite, se usa el atributo id del elemento anfitrión. |
item (hub-nav-item)Obligatorio | HubNavItem | — | El elemento de navegación renderizado por el hijo interno hub-nav-item. Gestionado automáticamente por hub-nav; rara vez se enlaza directamente. |
depth / isActive / isExpanded / forceAccordionMode (hub-nav-item) | number / boolean / boolean / boolean | 0 / false / false / false | Inputs de estado internos de hub-nav-item: profundidad de anidamiento, flags de activo y expandido, y comportamiento accordion forzado dentro de contextos móviles o de panel. |
items (hub-nav-item-list)Obligatorio | HubNavItem[] | — | Elementos renderizados por el hijo interno hub-nav-item-list. Gestionados automáticamente por hub-nav. |
panels (hub-nav-panel-container)Obligatorio | HubNavPanelState[] | — | Pila de estados de paneles abiertos renderizada por el hub-nav-panel-container interno en el modo de expansión panel. |
panel (hub-nav-panel)Obligatorio | HubNavPanelState | — | Estado de un único panel de drill-down renderizado por el hijo interno hub-nav-panel. |
itemTemplate / dropdownRenderMode / panelWidth / sidebarSide / showHeader / hideFirstPanelHeader (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | TemplateRef<unknown> | null / HubNavDropdownRenderMode / string / HubNavSidebarSide / boolean / boolean | — | Inputs de cableado interno que el hub-nav raíz reenvía a sus hijos (cada uno existe en el subconjunto de estos componentes que lo necesita, junto con la profundidad y las clases de propietario/orientación del overlay). Configúralos a través del input config de hub-nav en lugar de enlazarlos directamente. |
Outputs
Reacciona a lo que hace nav: 11 eventos a los que enganchar tu lógica.
| Nombre | Tipo | Descripción |
|---|---|---|
itemClick | OutputEmitterRef<HubNavItem> | Se emite cuando se hace clic en un elemento de tipo link. Proporciona el HubNavItem en el que se hizo clic. |
dropdownOpen | OutputEmitterRef<HubNavItem> | Se emite cuando se abre un elemento de tipo dropdown. |
dropdownClose | OutputEmitterRef<HubNavItem> | Se emite cuando se cierra un elemento de tipo dropdown. |
mobileToggle | OutputEmitterRef<boolean> | Se emite cuando se alterna el panel móvil. Proporciona true cuando está abierto y false cuando está cerrado. |
panelChange | OutputEmitterRef<HubNavPanelEvent> | Se emite cuando un panel se abre, se cierra, se profundiza o se retrocede. Proporciona el elemento, el índice del panel y el tipo de acción. |
railChange | OutputEmitterRef<boolean> | Se emite cuando el valor del modelo rail cambia, habilitando el enlace bidireccional [(rail)] y la persistencia en la aplicación. |
activeSectionChange (hubNavScrollSpy) | OutputEmitterRef<string> | Emite el id de la nueva sección activa cada vez que cambia la sección visible. |
clicked / toggleDropdown (hub-nav-item) | OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem> | Eventos internos de hub-nav-item: clicked emite el elemento junto con el evento DOM original, toggleDropdown emite el elemento dropdown que se está alternando. Ambos burbujean hasta los outputs de hub-nav. |
itemClick / dropdownToggle / panelOpen (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem> / OutputEmitterRef<HubNavItem> | Eventos de interacción con elementos reemitidos por los hijos internos de lista y panel mientras burbujean hacia hub-nav: itemClick (elemento junto con el evento DOM), dropdownToggle (elemento alternado) y panelOpen (elemento cuyos hijos deben abrir un panel). |
closePanel / backClick (hub-nav-panel) | OutputEmitterRef<string> | Los emite el hub-nav-panel interno con el id del panel cuando se pulsa el botón de cierre (closePanel) o el botón de volver (backClick). |
panelClose / panelBack (hub-nav-panel-container) | OutputEmitterRef<string> | Los emite el hub-nav-panel-container interno con el id del panel, retransmitiendo a hub-nav las peticiones de cierre (panelClose) y de vuelta atrás (panelBack). |
Templates
Hazlo tuyo — 3 plantillas para proyectar tu propio marcado.
| Nombre | Descripción | Ejemplo |
|---|---|---|
hubNavStart | Proyecta contenido personalizado en el slot de inicio. Horizontal: inicio visual (izquierda en LTR, derecha en RTL). Vertical: parte superior de la columna principal. | <hub-nav [items]="items">
<ng-template hubNavStart let-collapsed="collapsed">
<img src="logo.svg" alt="Brand" />
@if (!collapsed) { <span>App Name</span> }
</ng-template>
</hub-nav> |
hubNavEnd | Proyecta contenido personalizado en el slot final. Horizontal: final visual (derecha en LTR, izquierda en RTL). Vertical: parte inferior de la columna principal. | <hub-nav [items]="items">
<ng-template hubNavEnd>
<button type="button">Sign out</button>
</ng-template>
</hub-nav> |
hubNavItemTemplate | Sobrescribe el renderizado por defecto del elemento con una plantilla personalizada. Recibe HubNavItemTemplateContext con las propiedades $implicit (item), active, expanded y depth. | <hub-nav [items]="items">
<ng-template hubNavItemTemplate let-item let-active="active">
<span [class.fw-bold]="active">{{ item.label }}</span>
@if (item.badge) { <span class="badge">{{ item.badge }}</span> }
</ng-template>
</hub-nav> |