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 40 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. |
iconTemplate | TemplateRef<HubNavItemIconContext> | null | null | Plantilla que se dibuja en lugar de la clase de icono, en las entradas que declaran icon. Recibe HubNavItemIconContext con $implicit (el item) y rail. La directiva hubNavItemIcon 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. En un menú cuyas raíces se expanden de formas distintas solo queda una sección abierta: al llegar a una raíz en acordeón se cierra el panel de la raíz que dejas, y al revés. |
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)]. |
activeItemId | string | null (two-way: model) | null | Entrada que se marca como activa, nombrada por su `id` o por su `fragment`, cuando no es el enrutador quien dice dónde está el lector. Mientras tenga valor responde por todo el menú: el cotejo de rutas se aparta y la entrada marcada anuncia `aria-current="location"` en vez de `page`. Admite enlace en dos sentidos, que es como el espía de scroll mueve la marca. |
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. |
nav (hubNavScrollSpy) | HubNavComponent | null | null | El menú del que responde este espía. Enlazado, las dos mitades se juntan: la sección que el lector tiene delante marca su entrada, y una pulsación en una entrada desplaza aquí. No escribe en la URL ni añade nada al historial. Sin enlazar, el espía solo informa por `activeSectionChange`. |
scrollContainer (hubNavScrollSpy) | HTMLElement | null | null | El elemento en el que estas secciones se desplazan de verdad, cuando no es el que el espía encontraría subiendo desde ellas. Es además lo que mueve `scrollTo`, que es lo que impide que un salto se lleve por delante a todos los antepasados desplazables. |
clickSettleMs (hubNavScrollSpy) | number | 0 | Cuánto sobrevive, en milisegundos, la respuesta de una pulsación a que el lector parezca tomar el mando. Durante esa ventana se ignoran la rueda, el dedo y el teclado, así que un salto todavía en marcha no queda anulado a mitad de camino. `0`, el valor por defecto, deja el comportamiento anterior. |
sectionId (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; depth and forceAccordionMode also on hub-nav-item-list) | 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. hub-nav-item-list también admite depth y forceAccordionMode, para forzar un nivel entero de una vez. |
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 / isLast (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | TemplateRef<unknown> | null / HubNavDropdownRenderMode / string / HubNavSidebarSide / boolean / 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, e isLast marca el panel más externo de una pila para que cierre su borde. Configúralos a través del input config de hub-nav en lugar de enlazarlos directamente. |
overlayOwnerClass / overlayOrientationClass (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | string / 'hub-nav--horizontal' | 'hub-nav--vertical' | '' / 'hub-nav--vertical' ('hub-nav--horizontal' on hub-nav-item-list) | Cableado de overlay que el hub-nav raíz reenvía cuando los submenús se renderizan en un overlay a nivel de body: overlayOwnerClass es la clase única que ata un overlay a su navegación para el cierre por clic fuera, y overlayOrientationClass lleva la orientación de la navegación para que los estilos de contexto sigan aplicando fuera del árbol del componente. |
Outputs
Reacciona a lo que hace nav: 12 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. |
activeItemIdChange | OutputEmitterRef<string | null> | Se emite cuando cambia la entrada marcada, que es lo que hace que `activeItemId` admita enlace en dos sentidos. Un espía de scroll enlazado con `[nav]` informa por aquí de la sección en la que aterriza. |
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 — 4 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) { <hub-badge shape="rounded">{{ item.badge }}</hub-badge> }
</ng-template>
</hub-nav> |
hubNavItemIcon | Sustituye el glifo de cada entrada que declara icon, y nada más. Recibe HubNavItemIconContext con $implicit (el item) y rail, de modo que un menú puede dibujar sus iconos con ng-hub-ui-icons —o con cualquier otro pack— sin que la librería dependa de ninguno. Las entradas sin icon no se tocan. | <hub-nav [items]="items">
<ng-template hubNavItemIcon let-item let-rail="rail">
<hub-icon [name]="item.icon" [size]="rail ? 'lg' : 'md'" />
</ng-template>
</hub-nav> |